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stay In Control Wherever You Go. 



ow, both of these indispensable tools 
are updated to take full advantage of the 
world's most advanced operating system. 


For more than a decad ijtnbuktu Pr o and netOctopus 
have been the leading remote control, file transfer and 
systems administration applications for the Mac OS. 


Mac OS X Ready 


Windows XP Ready 


Timbuktu Pro 

Whether you’re at home or at work, Timbuktu Pro allows you to operate distant 
computers as if you were sitting in front of them, transfer files or folders quickly 
and easily, and communicate by instant message, text chat, or voice intercom, 
http: / / www.t i mbu ktupro.com 


netOctopus 

Intuitive and powerful, netOctopus can manage a network of ten or 10,000 
computers. Inventory computers, software and devices on your network; distribute 
software; configure remote computers; and create custom reports on the fly, 
http;// wvvw.netoctopus.com 


Learn more, try it, or buy it online. Call us at 1-800-485-5741. 
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YOUR DATABASE SERVER WITH THE 

C-TREE SERVER SDK 



• Enhance our server with your own 
euslom server-side functionality 

• Move functionality from the client-side to 
the server-side to reduce network traffic 
and increase performance 

• Mixlify or replace entire server 
subsystems 

• Complete source for the server 
mainline, key server 
subsystems, and clicnl-sidc 

• Flexible OEM licensing 


Today’s database demands ttre often too complex for traditional database servers, 
'fhe functionality and precise level of control you need is simply not available- 
Perhaps you need alternate sort criteria for your data or a special twist in the 
threading or communication logic- 

FairConi’s c-tree* Server SDK allows you to create a cusloini/.cd, 
industrial-strength server designed for your particular needs. Use 
FairCom’s kcmel, with over 20 years of proven stability, or override 
functionality within specific subsystems to implement your own 
subtleties. Move your application’s data I/O functions to the 
server-side to decrease network traffic and increase 
performance! 

FairCom's c-tree Server SDK i.s used by companies 
worldwide such as Software AG and Citibank". It’s 
integrated seamlessly into c-tree Plus and includes 
complete source code to the server mainline and all the 
interface subsy.stems to the c-trcc Server And 
best of all, once you've created your unique, 
customized server, it is easy to install and 
administer: no DBA required! 


Visit www.faircom.conn/ep/nnt/sdk today to take control of your server! 
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PERL 

PROGRAMMING 


hy Paul Ammann 


Writing Portable Perl 


Perl runs im numeroas oper^iting sysiemi>. While most ol' 
them share much in common, they also have their own 
unique features. 

Tills article is meant to help you to find out what constitutes 
piatable Perl code. Tliat way once you make a decision to write 
porrably, you know^ where the lines are drawn, and you can stay 
wiiliin ihcm. 

1'here Is a Lradeoff between taking full advantage of one 
particular type of computer and taking atlvaniage of a hill range 
of them. NaUirallyj as you broaden your range and iK^come moR" 
diverse, the a>mmon factors drop, and you arc left witli an 
increasingly smaller area of common ground in which you can 
operate to accomplish a particular task. Tints, when you liegin 
attacking a problem, it Is iinpt>rtant to consider under which part 
of the tradeoff curve you want to operate. Specifically, you tnusl 
decide whether it is impoitam tltai the task that yon are coding 
have the full generality of being portable, or wUclIilt to just get 
the job done riglit now. This is the hardest choice to be made. 
1he rest is e;tsy, because Perl pnivides many choices, whichever 
way you want to approach your problem. 

Lxjking at it another way, writing portable code is usitally 
alx)Ut willfully limiting your available choices. Naturally, it takes 
discipline and sacrifice to do that. The product of portability and 
convenience may Ixi a constimr, You have been warned. 

Be aware of two important points: 

Not all Perl programs have to be portable. There is no 
reason you should not use Perl as a language to glue Unix uhAs 
together, or to prototype a Macintosh applicatir)n, or to manage 
the Windows registry. If it makes no sense to aim for portalxlity 
for one reason or another in a given program, tlien d<m'i bother. 

Nearly all of Perl already is portable. Don't be fcx>led 
into thinking that il is liartl to create p<>itable Perl code. It isn't. 
Perl tries its level best to bridge tlie gups lieiween what's 
available on different platforms, and all the means uvaiial>]e to 
use those features. Tims almost all Perl code runs on any 
machine without modification. But there am .some significant 
issues in wTiring portable code, and this document is entirely 
about those issues. 

lleres the general rule- When yrni approach a task 
commonly done using a whole range of platforms, think alx)Ut 
W'riting portable ccxle. 'that way, you dt)iVt sacrifice much by 
way of tile implementation choices you can av;iil yourself of, and 
at the same time you can give your users lots of platform 
choices. On the other hand, w'hen you have to lake advantage 


o{ some uniciue feature of a particular platform, as is often die 
case with systems programming (whether for Unix, Windows, 
Mac OS, VMS, etc.}, consider vvriting platform-specific code. 

When the code will run on only two or three operating 
systems, you may need to c emsider only the differences of tliose 
particular systems. Tlie imporiani thing is to decide where the 
crxle will run and to be deliberate in your decision. 

The materia] below is separated into three main sections; 
main issues of portability (l.ssiies, p hit form-specific issues 
(Platforms, and built-in Perl functions tluii behave differently on 
various ports (Punction Implementations. 

Tliis infonnalion sh(>uld not be coasidered complete; it 
includes possibly transient infomialion alxHit kliosyncmsies of 
some of the ports, almost all of wiiich are in a slate of constant 
evolution. Thus, this material should lx considered a perpetual 
work in progress. 

1. Issues 

Newlines 

In most operating systems, lines in files are lerminated by 
newlines. Jti.sr what is usctl as a newline may vary from OS to 
OS, Unix traditionally uses \012, one type of DQSish I/O uses 
\015\()12, and Mac OS uses \01S. 

Perl uses \n to represt.mi the 'logical newline, where what 
is logical may dejxrnd on ihe platform in use. In MacPerl, \n 
always means \015. In DOSish txris, \n usually means \012, but 
when accessing a file in "text" mode, STDIO iranslaies it to (or 
from) \015\012, depending on whether youYe reading or 
writing. Unix does the same tiling on ttys in canonical mode. 
\015\012 is commonly referred to as CRLF. 

A common cause of importable programs is the misuse of 
ehop{) to tnm newlines; 

# XXX UKrORTABLEI 
while {<FILE» I 
chop: 

#array ^ split(/:/): 

I 

You can get away with this on Unix and Mac OS (they 
have a single character end-of-line), but the same program 
will break under DOSish peris because you're only chopOtng 
luilf the end-ofdine. instead, chompC) should be used to trim 
newlines. The DuncenFiles module can help audit yotir code 
for misuses of chop(). 
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If a picture is worth a thousand words, 
imagine how priceless a movie would be. 



Snap;? Pro X 2.0 allows you to effortlessly record anything on your screen, saving it as a QuickTime® 
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when dealiag with binary files (or text files in binary 
mode) he sure lo explicitly set $/ to the appropriate value for 
your file format before usin^ chompC). 

Because of the mtxle Ininslation, DOSish peris have 
limitations in using seek and tell on a file accessed in ""text” 
mode- Stick to seek-ing lo locations you got from tell (and no 

others), and you are usually free to use seek and tell even in 

""text" mode. Using seek or tell or other file operations may l>e 
non-portable. If you use binmode on a file, however, you can 
usually seek and tell with arl)iirary values in safety. 

A common misconception in socket programming is that 
\n eq \012 everywhere. When using protocols sucit as 
common Internet protoetjls, \012 and \015 are called for 
specifically, and the values of the logical \n and \t (carriage 
return) are not reliable. 

print SOCKET ‘'Hi there, client! \r\n*; WRONG 

print SOCKET "Hi there, client!\015\012": | RIGHT 


However, using \ 015\012 (t>r \cM\i% or \xOD\xOA) can l>e 
tedious and im.sightly, as w'ell as confusing to those maintaining 
the code. As such, the Socket module supplies ilie Riglil Thing 
for those who want it. 

use Socket ijwtiaEimT :crlf): 

print SOCKET "m ther«. clientiSCRLF" # RIGHT 

Wlien reading from a s{K:ket, remember that the default 
input record separator $/ is \n, but robust stxkei ctKle w^ill 
recognize as either \()12 or \0I5\012 as end of line: 

while {<SOCKET>) I 

II ... 

I 


Because* lx)tJi CRLF anti U* end in LF, the input retx)al sep^l^ 4 lto^ 
an lie sen to IF and any CM sirippenl later. Better lo write: 

uB<j Socket £jw( DEFAULT :crlf]: 

locaKS/) = LF: if not noodetl if $/ is already \012 

while (<S0CKET» I 

s/$CR?$LF/\n/: # not If socket uses LF or CRLF. OK 

# e/\015?\0I2/\ii/; same thing 


I'll is example is piieferred over the previous one"—even lor 
Lfnix platfonns—because now any \015’s (AcM*s) are stripped 
out (and there was much rejoicing). 

Similarly, functions that return text data—such as a 
function dial fetches a web page—should sometimes translate 
newlines IxTore reluming the data, if the 7 *ve not yei been 
iranslated lo the local newline representation. A single line of 
code will often suffice: 

$data s/\0J5?\012/\a/£: 
return ^data: 


Some of this may \yc confusing, Here's a handy reference lo 
the ASCII CR and LF characters. You can print it out and stick it 
in your wallet. 

LF eq \0J2 eq \xOA eq \cJ eq chr(IO) eq ASCII 

10 

CR eq \01i eq \kOD eq \cn eq ctir(n) eq ASCII 

U 

I Unix I DOS I Mac I 


\n 

LF 

t>F 

1 1 

\r 

CR 

CR 

lf 

\n ■ 

U 

CRLF 1 

CR [ 

\r * 

CR 

CR 1 

1 LF \ 


* text-mode STDIO 


ITie Unix column assumes that you are not uceexsing a 
serial line (like a tty) in canonical mode. If you are, then CR on 
input becomes and "\n^' on output Ixcaxmes CRLF. 

These are just the most common definitions of \n and \ r in 
FctI. There may well be others, Fi^r example, on an EBCDIC 
implementation suc h as z/OS (OS/39<)) or OS/400 (asing the ILlv, 
the EASE is ASCII-based) the above material is similar lo '"Unix" 
l)ul the code numluTS change: 


21 

0037 

LF 

LF 

37 

eq 

eq 

\02i 

\04S 

eq 

eq 

\*15 

\x25 

eq 

eq 

VcO 

eq 

clri:(21) 

ckrd?) 

eq 

eq 

CP-1047 

CP- 

13 

CR 

eq 

Vo 15 

eq 

\xDD 

eq 

\cH 

eq 

chr(n) 

eq 

CP 1047 

13 

CR 

eq 

\ 0 I 5 

eq 

\x0» 

eq 

\cN 

eq 

chr U 3) 

eq 

CP-0037 


I t/OS I 05/400 I 


\n 

LF 

LF 

\r 

CR 

CR 

\n * 

LF 

LF 

\r * 

CR 

CR 


’ text caode STDIO 


Number?* endianness and Width 

Differem CPUs sioa" integers and noaling-fX)inT numbers in 
different orders (called endi:inaes.s) and widths {32-bit and 64- 
Ihi being the most common today). This affects your programs 
w4ien they attempt to tmnsfer nu miners in liinary format from 
one CPU archilecUire to another, usually either "live" via 
network connect ion, or by storing the numliers to secondary 
-Storage such as a disk file or tape. 

Conflicting storage orders make utter mess <Hit of tlie 
numlx-‘rs. if a little-endian host (Intel, VAX) stores 0x123^13678 
(.^05419896 in decimal), a btg-cndian host (Motorola, Sparc, PA) 
reads it as 0x78563412 (2018915346 in decimal). Alpha and MIPS 
can be eitlier: Digilal/Compaq used/uses them in little-endian 
nu>de; SGl/(.^ray uses them in big-endian mode. I'o avoid this 
problem in network (socket) ct)tineditms use the pack and 
unpack fonnats n anti N, the "network" orders. These are 
guaranteed to f)e |K3riable. 
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you CJft explore I lie endianness of your platform by 
unpacking a data stmcUire packed Ln native format such as: 

print impac’.k(“h*’'» pack(*"32", 1» 2)K 

?/ '10002000' on e.g^ Intel xS6 or Alpha 21064 In little-endian 
mode 

# '00100020' on e.g» Hotocola 08040 

If you need to distinguish Ixrtwcen endian archiieaures you 
could use either of the variables set like so: 

“ unpack E"h'* , packt^s*. 1)) /Ol/: 

$is_llttle_eiidian - unpack("h*"* packC*e"N 1)} /''!/: 

Differing widUis can cause truncation even bciween 
platforms of equal endianness. The platform of shorter width 
loses the upper parts of the number There is no gtKxl solution 
for this problem except to avoid transferring or storing raw 
Irinary numbers. 

One can circumnavigate both these prolilems in two ways, 
lather iransfcr and store numbers always in text Ibnriab insteatl 
of raw binary, or eise consider using modules like Data: iDumper 
(included to the standard distribution as of Perl 5,005) and 
Stumble (included as of perl 5.8). Kee[>ing all data as text 
significantly siiiiplihes rnaiters. 

The v-strings are portable only up to v2147483647 
(()x7FFFFFFF), ihat’s how far EBCDIC, or more precisely UTF^ 
EBCDIC will go. 

Files and Filesystems 

Most platforms these days stnicluir files in a hierarchical 
fashion. So, it Is reasonably safe to assume that all platfonns 
support the notion of a ‘"path*' to uniquely identify a Me on the 
system. How that path is really WTitien, though, differs 
considerably. 

Although similar, Pile fraih specifications differ between 
Unix, Windows, Mac Oh, OS/2, VMS, VOS, RISC OS, and 
probably others. Unix, for example, is one of the few OSes that 
has the elegant idea of a single rfx)r director>^ 

DOS, OS/2, VMS, VOS, and Windows can work similarly to 
Unix w'iili / as path separator, or in their own idit>syncratic ways 
(such as having several rtKJl directories and various "unrcKXed" 
devU:e files such NIL: and LPT:). 

Mac OS uses : as a path separator instead of /. 

The filesystem may support neither hard links (link) nor 
symbolic links (symlink. readlink, Isiat). 

Tlie filesystem may support neither access timestamp nor 
change timestamp (meaning that about the only portable 
timestamp is die nuxlilicaiion limesiamp), or one seccjnd 
granularity of any timestamps (e.g. the FAT filesystem limits the 
time granularity U) two seconds), 

llie "Tnode change Limestamp” (the -C filetesl) may really 
be the "\‘neation timestamp" (wliich it is nor in UNIX). 

VOS Perl c:an emulate Unix filenames with / as path 
separator. The native pathname characters greater-than, less- 


thati, number-sign, and fiercent-sign are always accepted. 

RISC OS Perl can emulate Unix filenames with / as path 
separator, or go native and use , for path .separator and : to 
.signal filesystems and disk names. 

Don't assume UNIX filesy.slem access semantics: that read, 
write, and execuie are al! the permissions there are, and even 
if they exist, that their semantics (for example what do r, w, 
and X mean on a directory) are the UNIX ones. 4'he various 
UNIX/POSIX compatibility layers usually try to make 
interfaces like climodO w'ork, but sometimes there simply is 
no gotxl mapping. 

If all this is intimidating, have no (well, maybe only a little) 
fear. There are tntKlules that can help. The FilenSpcc modules 
provide methods to do tlie Right Thing on whatever platform 
happens to be running the program. 

use File: :8pec: :Functioris: 

chdir{u|Kiirt)) :# go up one directory 

$file * catfile(curdir(), ‘flte.txt'); 

if on Unix and Win32. './temp/fne.txt' 

if on Mac OS» ': temp: f 1 Ic. rxt' 

if on VKS. ■ [.temp] flle.txt * 

Filc::8pec is available in the standard distribution as of 
version File: :Spec:: Functions is only in File::Sp€c 0.7 

and later, and .some versions of perl come with version 0.6. If 
Filc::Spcc is not Lijxlated to 0.7 or later, you must use the object- 
trrienicd interface from File::Spec (or upgrade Filc::Spec). 

in general, production code should not have file paths 
hardcoded. Making them user-supplied or read from a 
configuration file is better, keeping in mind that file path syntax 
varies on differeni machines. 

'fhis is especially noticeable in scripts like Makefiles and test 
suites, which often assume / as a path separator for 
sulxlirccU>rics. 

Also of use is FileiiBasename from the standard distribution, 
whicli splits a pathname into pieces (ba,se filename, full path to 
directory, and file suffix). 

Even when on a single plaifomt (if you can call Unix a 
single platform), remember nt)t to count on the existence or the 
contenLs of particular .system-specific files or diretiories, like 
/etc/passwd, /elc/sendmaiLconf, /etc/resolv.conf, t>r even 
/rmp/. For example, /elc/passwd may exist but not contain the 
encrypted password.s, because the system i.H using some form of 
enhanced .seeuriry. Or it may not contain alt ihc accounts, 
because the system is using NIS. If code does need to rely on 
such a file, include a description of the file and its fc>rmat in the 
eexie's documentaiion, then make it easy for llie user to override 
the default location of ihe file. 

Don't as.sume a text file will end with a newiine. 'Iliey 
slK)uld, Imi people foiget. 

Do not have two files or directories of the .satne name with 
different case, like test.pl and Tesl.pl, as many platfonns have 
cuse-inseositive (or at least case-forgiving) filenames. Also, try 
not to have mm-wtmi characters (except for.) in the names, and 
keep them to the 8.3 convention, for maxintum portability, 
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onercms u burden though ihi.s may appear. 

Likewise, when using the AiitoSphf mcxlule, try to keep 
your functions Lo 8.3 naming and case-in sen si Live conventions; 
or, at the least, make it so the resulting files have a unique (case- 
insensitively) first 8 characters. 

Whitespace in filenames is tolerated on most systems, but 
not alb and even on systems where it iriiglit lie tolerated, some 
utilities might become confused by such whitespace. 

Many systems (DOS, VMS) cannot have more than one , in 
their nicnamcs. 

Don’t assume > won’t be the first character of a filename. 
Al ways use < explicitly to open a file for reading, or even better, 
Utse the ihi-ee-arg version of open, unless you want the user to 
be able to s|>ecify a pipe open. 

openCtlLE, '<*, Sexisting_flie) or die : 

if filenames might use strange charactens, it is safest to 
open ii with sysopen instead of open, ojxm is magic and can 
translate characters like >, <, and J, which may be the wrong 
thing to do. {Sometimes, though, it’s the right thing.) Three-arg 
open can also help protect against this transhuion in cases 
where it is undesirable. 

Don't use : as a part of a filename since many systems use 
that for their own semantics (Mac OS Ohissic for separaiing 
pathname components, many networking schemes and utilities 
for separating the riodename and the paihnanic, and so on). For 
the same rea,sons, avoid ; and 1. 

Don’t assume that in pathnames you can collap.se two 
leading siaslics // into one: some networking and clustering 
filesystems have special semantics for tliat. Lei the OfKTaling 
system to sort it out. 

llte portable filename characters a.s defined by ARSI C are 

a b c d e f g h i j k ,1 in n o p ej r i u v w x y z 
AHCaKFGaiJKLMNOPUKTUVWXyZ 
0 1 2 3 4 5 6 7 S 9 


and tile shouklii'l be the first cliaracten If you want to 
l)e liypercorrect, stay case-insen si live and within the 83 naming 
convention (all the files and directories have to Ix’ unique within 
one directoiy if their names are lowercased and truncated to 
eight < haracters before the if any, and to three chanicters after 
the ., if any). (And do not use .s in directory names.) 

System [nteraction 

Not all platforms provide a command line. These are 
usually platforms that rely primarily on a Graphical User 
Interface (GUI) for user interaction, A program requiring 
a command line interface might not work everywhere. 
This is |>rol>aI)ly for the user of tlie program to deal w itli, 
so don't stay up late worrying about it, 

Some platforms can’t delete or rename files held open hy 
the .system, this limitation may also apply to changing filesystem 


meiaiiifurmalion like file pemiissiuns or owners. Remember to 
close files when you are done with them. Don’t unlink or 
rename an open file. Don’t tie or open a file already tied or 
opened; untie or dose it first. 

Don’t open the same file more than once at a time for 
wriling, as .some operating systems put mandatory locks on 
such files. 

Don’t assume that write/modify pemiission on a directoty 
gives the right to add or delete files/directories in that directory. 
That Ls filesy.siem specific: in some filesysienis you need 
write/modify permission also (or even just) in the file/directory 
itself. In some filesystems (AFS, DPS) the permission to 
add/delete directory entries is a completely separate pennission. 

Don’t assume tliat a single unlink completely gets rid of 
the file: some filesystems (most notably the ones in VMS) have 
versioned filesystems, and unlinkO removes only the most 
recent one (it doesn’t remove all tlic versions t)ccausc by 
default the native tools on those platforms remove ju,si the 
most recent version, mo). The portable idiom to remove all the 
versions of a file is 

1 while unlink, “file**; 

This will tenninatc if the file is undclcleablc for some 
reason (protected, not there, and so on). 

Don't count on a specific environment variable existing in 
%ENV. Don’t count on %ENV entries being ca.se-scnsitive, or 
even case-preserving. Don’t try to clear %ENV by saying %ENV 
= ();, or. if you really have to, make it conelitional on $aO ne 
VMS’ since in VMS the %BNV table is much more than a per- 
[>rocess key-value string talde. 

Don't count on .signals or^MIG for anything. 

Don't count on filename glohbing. Use opendir, readdtr, 
and dosedir instead. 

Don't c(junt on per-program environment variables, or per- 
prognim current directorie.s. 

Don’t count on specific values of $!, neither numeric 
nor especially the strings value.s— users may switch their 
locales causing error me.ssages to be translated into their 
languages. If you can inisi a POSlXish environment, you 
can portably use the symbols defined by the Ernia 
module, like ENOENT. And don’t trust on the values of $! 
at all except immediately after a failed system call. 

Command tiaines versus file pathnames 

Don’t assume that the name used to invoke a command or 
program with system or exec can also he used to test for the 
existence of die file that holds the executable code for that 
command or program. First, many .systems have "internal” 
command,s that are built-in to the .shell or OS and while these 
commands can lie invoked, there is no corresponding file. 
Second, some operating systems (e.g., Cygwin, DJGPP, OS/2, 
and VOS) have required suffixes for executable files; these 
suffixes are generally permitted on the command name but are 
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not rL'tjturotL Thius, ;i I'ommand like "'per!" might exist in i\ file 
named "jK^r^ "'|H:rLexe'\ or ''|x.Tl.pm'\ depending on the 
operating system, llie variable ''_exe” in the Conflg rin>dulc 
liolds the exeairable suffix, if any. 'lliird, the VMS (XJit curetully 
sets u[> $^X and SConfiglperlpaihl so that no further prtKessing 
is required. This is just us well, Ix^eause die mateliing regular 
expre.ssion usetl below would then have to deal with u possible 
trailing version nuinl>er in the VMS file name. 

To eonvert to a file padmarne, taking atToiinl of the 
requirements of the various operating system possibilities, say: 
use Omfig; Slhisperl = S^X; if (,$ao ne 'VMS') i$thi.sperl = 
5Configl_exel unless SlliisjK'il m/$Config|_exel$/i;l 

lb convert $Config(perlpathl to a file paliiname, say: usc‘ 
Config; Sihisperl - $Configlperlpalhh if ($^0 ne 'VMS') l$thisjxTl 
$Config(_cxcl unless SihlspcTl m/SConfigLexel$/i;l 

Netwi)rking 

• Don't assume that you can reach the public Internet. 

• Don't assume that diere is only one way to gt^t through 
firewalls to die public Internet. 

• Don't assume that you can reai^h outside world through any 
other port thati 8d, or stniie weh proxy, ftp is hlix’ked by 
many firewalls. 

• Don’t a.s?iunie that you can send email by connecting to the 
kK'at SM'IT j>on. 


• Don’t assume that you can reach yoursell' or any ncxle by the 
name localhost'. Tlie same goes for '127.0.0.1You will fiave 
to try both. 

• Don’t assume that the host has only one network card, or 
that it can't bind to many virtual IP addressc\s. 

• l>on t a.ssume a particular network device name. 

• Don’t assume a particular set of iocilO.s will work. 

• Don’t assume diat you can [)iag hasis ami get replies. 

• Don't assume that any particular port (service) will resp«>nd. 

• Don’t assume Miat Sysr:Hostname() (or any other API or 
command) reUims either a fully cjiuiliried hostname or a non¬ 
qualified hostname: it all depends on how the system had 
been configured. Also remember things like DIICP and 
KAT— the ho,slname you gel hack might mil lx* very useful. 

All the aNive "'don't'':s may look daunting, and they are — 
but the key is to degrade gnicefiilly if one cannot reach the 
particular network semce one wants. (Imaking or hanging do 
not look very profeasional. 

Interprocess Commuiiicatioii (IPC) 

In general, don’t directly access the system in code meant 
to lx- portable. That means, no .system, exec, fork, pipe, ", qx//, 
open with a I, nor any of ilie oilier tilings that makes being a 
perl hacker worth being. 
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Commands that launch external processes are generally 
sup}X>r(ed on most pkitforms (though many of ihetn do not 
support any type of forking). The problem widi using thetn 
arises from whai you invoke them on. External tools are often 
named differently on different platforms, may not be availal)le in 
the same loauion, might accept difTercni arguments, can l>ehave 
differently, and often present tlieir results in a platform- 
dependent way. Thus, you should seldom depend on them to 
produce consistent re.sult.s. (Then again, if yt)uVe calling netstat 
-a, you probably don't expect it to run on both Unix and CP/M.J 

One especially common bit of Peri code is opening a pipe 
to scndmaih 

opfin{MAIL. ‘ I/usr/Iib/sendioaii -tV) 
or die ^^cannot fork sendmail: $!"; 

'ITiis is fine for system.s pnigramming when send mail is 
known to be availal^le. But it is not fine for many non-Unix 
systems, and even some Unix systems that may not have 
sendmail installed. If a portable solution is needed, see the 
various distribitlions on CPAN that deal with it. Majl::Mailer and 
Mail::Send in the MailTtwIs distribution are commonly used, and 
provide several mailing methods, including mail, sendmail, and 
direct SHIV (via Nei::SMTl’) if a mail transfer agent is not 
available. MaihiSendmail is a standalone module that provides 
simple, [jlatform-independent mailing. 

The Unix System V IPC (insg^O, sem*0, sljm*()) is not 
avaiialrle even on all Unix plalldrins. 

Do not use cither the f>are result of pack{‘‘N", 10, 20,30,40) 
or bare v-strings (such as v10.20.30.40} to repre.scm IPv4 
addresses: both forms just pack tlic fijur bytes into network 
order That liiis would lie equal to the C language in^addr stnict 
(w'hich is what the socket code internally uses) is not 
guaranteed, 'Jb be portable use the rt)uliocs tT the Scxket 
extension, such as inci_aion(), ineMitoaO, and sockadclr_in(). 

Tlic rule of thumb for portable ccxle is: Do it all in portable 
Perl, or use a module (that may internally iinplumcnl it with 
platform-specific code, but expose a common interface). 

External Subroutines (XS) 

XS code can usually be [iiade to work with any piatlbrm, 
but dependent libraries, header files, etc,, might not be readily 
available or portable, or the X.S code itself mighi be platform- 
specific, ju.sl as Perl ix>de iiiighi be. If the libraries and headers 
are portable, tlicm ii is normally reasonable to make sure the XS 
ctxle is poriahle, too, 

A different lypt^ of portabiliiy issue arises w'hen writing XS 
ccxlc: availability of a C cunipder on the end-useTs system. C 
brings wath it its own portability issues, and writing XS code will 
expose you to some of [hose. Writing purely in Perl is an easier 
way to achieve p<jrtabiliiy. 

Standard Modules 

!n general, the standard mtKlules work across platforms. 
NtJiable exceptions are the CPAN mcxliile (which currently 


makes connections to external programs that may ooi lx: 
available), platfonri-specific modules (like Rxil]iils::lVlM_VMS), 
and DBM modules. 

Tliere is no one DBM module available on all platforms. 
SDBM_nie and the others are generally available on all Unix and 
DOSish ports, but not in Mac’Perl, wliere only NBDM_File anti 
DB_File are available. 

The good news is that at least some DBM module should 
lx* available, and AnyDBM_File will use whichever module it 
can find. Of course, then the code needs to be fairly strict, 
dropping to the greatest common factor (e.g., not exceeding IK 
for each record), so that k will work with any DBM module. See 
the AnyDBM_File man page for more details. 

Time and Date 

Fhe system's notion of lime of day and calendar date is 
controlled in widely dilferent W'ays. Don't assume the timezone 
is stored in SENVITZl, and even if it is, don’t assume that you 
can control the timezone through that variable. Doni assume 
anything about the three-1 el ter timezone abbreviations (for 
example that MST would lx the Mountain Standard Time, it's 
Ixen known to stand for Moscow Standard Time). If you need 
to use timezones, expres.s them in some unambiguous format 
like the exact number of minutes offset fn>m U'rC, or the POSTX 
timezone fomiat. 

Don't assume that the epoch starts at tK):00:00, January 1, 
197(}, IxcaiLse ihai is OS- and implementation-specific. It is 
txaicT to store a date in an unambiguous representation. The ISO 
H6()1 .standard defines YYYY MM DD as the dale format, or 
YYYY MM-DDTHH-MM-SS f I hat’s a Ikeral T” separating the 
date from the time), l^lease do use tlie ISO 8601 Instead of 
making us to guess w^hai date 02/03/04 mighi lx. ISO 8601 even 
sorts nicely as-is. A text representation (like "'1987-12-18") can 
lx easily eonveriLxl into an OS-sjx*cific value using a module 
like Dale::Parse. An array of values, such as those returned by 
localtime, can lx converled to an OS-specific representation 
using Time:djtx:al. 

When calculating specific limes, such as for tesLs in time 
or date modules, it may he appropriate to calculate an offset 
for the epoch. 

require Time;:Local: 

Soffaol " Tliiie::I.OKal::r.iiiie|!a( 0 . 0 . 0 . 1 . 0 . 70 ): 

The value for $offsel in Unix will be 0, but in Mac OS will 
be some large number. Soffsel can I lien he added to a Unix time 
value to gel what should l>e the pmper value on any system. 

On Windows (at least), you shouldn't pass a negative value 
to gmtime or localtime. 

Character sets and cliaracter encoding 

A.ssume very little about cha racier sees. 

Assume nothing about nimiencai values (ord, chr) of 
characters. Do not use explicit code point ranges {like \xHH- 


12 


Wri hkc Pohtahijt: Pi:ki. 


MacTech • VOUJMK 20, ISSIIK 7 





Complete Sourte Control 

cbatigl^ the iiwrfrf 

Iff sifftware develojtment 

md Defett Kmuigemont 

for Mm OS X 



Effective source code control and defect tracking require powerful, 
flexible, and easy-to-use tools—Surround SCM and TestTrack Pro 


• Complete source code control with private 
workspaces, automatic merging, role-based 
security,and more 

• Comprehensive defect management — track 
bug reports and change requests,define 
workflow, customize fieids 

• Fast and secure remote access to your source 
files and defects — work from anywhere 

• Advanced branching simplifies managing 
multiple versions of your products 


* Link code changes with defects and change 
requests — know who changed what, when, 
and why 

’ Scalable and reliable cross-piatform, 
client/server solutions support Mac OS X, 
Windows, Linux, and Solaris 

* Exchange data using XML and ODBC, extend 
and automate with SOAP support 

* Licenses priced to fit your budget 


Seapine Software Product Lifecycle Management 
Award winning, easy-to-use software development tools 


Seipmt: 

Surround 5C/M 

Sk’uplrn- 

TestTrack 

PRO 

4 product iiiiines listed heiein are registered tnrdenmb ol ied respective ewneis. dll rights reserved. 



Download Surround SCM 
and TestTrack Pro at 
www.seapine.com 
or call 1'888>683-64S6 


































\xHH); use kn example symbolic diaraaer cbisses like prints I 

Do noi assume ihai ilie alphabetic characters are encoded 
conligiioiisly (in the numenc sense). There may be gaps. 

Do not assume anything about the ordering of the 
characters. ’I he lowercase letters may come Ixtfore or atier itie 
uppercase letters; the k)werLase and uppercase may be 
interlaced so that both 'a’ and A' come before '■!>’: the accented 
and other international chanicters may lie interlaced so ihai a 
conies before 'h’. 

laternationalization 

If yon may assume POSfX (a rather large assumfition), you 
may read more* aliout the POSIX locale system from the 
perllocale manpage. 'fhe locale system at least attempts to make 
things a little bit more poitable, or at least more convenient and 
nalivc-friendiy ft>r nf>n-English users. The system affects 
character sets and encoding, and date and time formatting— 
amongst other things. 

If you really want to be internationah you should consider 
Unicode. See the perluniintro manpage and the perl Unicode 
manpage for nic>rc information. 

If you want to use non-ASGl byies (ouiskle the bytes 
OxOtl.OxTf) in the ""stmree code" of your code, to he portable 
ytHi have to be exfilicit alx)ut what !>ytes they arc. Someone 
might for example he using ytuir code under a nTK-8 locale, in 
which nise random native bytes might be illegal (' MaHormed 
UTF-B This means that for example embedding ISO H859-1 
byres beyond 0x7f into your strings might cau.se irouble later. If 
the bytes are native 8-bit bytes, you can use the liyle.s pragma. 
If I he Itytes are in a string (regular expression being a curious 
string), you can often also use the \xllll notation instead of 
embedding the bytes as-is. If they are in some particular legacy 
enc'oding (ether single byie or someihing more complicated), 
you can use the encoding pragma. (If you want to write your 
code in liTF-8, you can use either the utfS pragma, or ihe 
encoding pragma.) The l>yies and utfS praginuia are available 
since Per! 5.6.0, and the encoding pragma since IVrl 5.8JJ. 

System Resources 

If your code is destined for systems with severely 
constrained (or missing!) virtual memory systems then yon w'anr 
to he e.specially mindful of avoiding wasiefni consirucissut h as: 

^ NOTE: thii5 is tio longer "bad" in perl5.D05 
for (0,,10000000] II H bad 

for (my $x = 0 : $jc <= 10000000 : [] | good 

Clines - <VEKY_LARGE_F1LE>:# bad 

vhilf? {<FILE>] $ I # smetintes bad 

$filp = jotnCV, <FTLE>]: tf better 

Tile last two constructs may appear iminruitive to nicest 
people. The first repeatedly grows a stiing, whereas the second 
a I locales a large chunk of memory in one go. On some systems, 
the second is more efficient that the first. 


Security 

Most multi-user [dalforms provide basic levels of security, 
usually implemented at the filesystem level, Some, however, do 
not— unfortunately. Thus the notion of user id, or “home" 
directory, or even the state of being logged-in, may be 
unrecogniKable on many platforms. If you write prognims ihat 
are security-conscious, it is osimlly best to know what type of 
system you will be running under so that you can write code 
explicitly for that platform (or class of platforms). 

Don't assume the UNIX filesy.stem access semantics: the 
openiiing .system m the niesysiem may be using some ACL 
systems, which are richer languages than the usual rwx, Even if 
the rwx exist, their semantics might different. 

(From security viewpoint testing for pcnTiis.sions IxTure 
attempting to do something is silly anyway: if one tries this, there 
i.s potential for race conditions— someoiie or someihing might 
change the |3iTmLssion.s l>eiween the permissions check and the 
actual operation. Just try die operation.) 

Don't assume the UNIX user and group semantics: 
especially, don't expect the $< and $> (or llie U and $)) to work 
for switching identities (or meniberslhj>s). 

Don't assume set-uid and set-gid semantics. (And even if 
you do, think twice: set-iikl and set-gid are a known can of 
security worms.) Most multi-user plal forms provide basic levels 
of .security, usually implemented at the file.sy.stem level. Some, 
however, do not— imtbrrunately. Thus the notion of user id, or 
'‘home" directory, or even the state of being logged-in, may be 
iinrecogni;^able on many plaiforms. if you write programs that 
are security-conscious, it is usually best to know what type of 
system you will be running under so that you can write code 
explicitly for that platform (or class of f)laiforms). 

Don’t assume tlie UNIX filesysiem access semantics: the 
operating system or the filesystem may he using some ACL 
sy.siems, which art^ richer languages dian die u.sual rwx. Even if 
the rwx exist, their semantics might be different. 

(From security viewpt)int testing for jiermLssions before 
a I tempting to do someihing is silly anyw^ay: if one iries diLs, there 
is poleniial for race conditions— someone or something might 
change the permissions between the permi.ssions check and the 
actual operation, just try the operation.) 

Don’t a.ssnme ihe UNIX user and grouf) semantics: 
es[>ecially, don’t expect the $< and $> (or the $( and $)) to work 
for .sw itching identities (or memberships). 

Don't assume set-uid and set-gid semanlics. (And even if 
you do, iliink twice: set-uid and set-gid are a knowm can of 
security wortns,) 

.Style 

For those times wlien it is necessary to have platform-specific 
code, consider keeping the plaifbrm-spedfic code in one place, 
making porting to other plat Firms easier. Use the Cotifig module 
and the special variable $aO to differentiate platforms, as 
described in PLATFORMS. 

Be careful in the rests yon .supply with your iruxlule or 
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pi’ogranis. Mcxlule ccxle may lx? Rilly portable, hut its tesLs might not 
lie. Tills often hiippens when tesLs ^spawn t)ff odier processes or call 
external pix>grams to aid in the testing, or when (as noted above) 
the tests assume certain things about the file-system and paths. Be 
careful not to depend on a spec:Efic output style for errors, such as 
when eiiecking $! after a failed sysletn calf Using $! for anything else 
than displaying it as output is doubtful (though see the frmo 
module for testing reasonably portably for error value). Some 
plai forms expect a certain output fonnal, and Perl on those 
piatfoniis ni:ty have lieen adjusted accordingly. Most specifically, 
don’t anchor a regex when testing an error value. 

CPAN Testers 

Modules uploaded to CPAN are tested by a variety of 
volunteers on differeni plaiform.s. These CPAN testers are 
notified by mail of each new upkjad, and reply to the list with 
PASS, FAIL, NA (no! applicable to this platfomi), or UNKNOWN 
(unknown), along with any relevant notations. 

The purpose of the lesling is twofold: one, Lo lielp 
developers fix any problems in their code that crop up because 
of lack of testing on other platfnnns; two, lo provide users with 
information about whelher a given module works on a given 
platform. 

Mailing list: cpan-testers@perl.oig 

Testing results: httpy/testers.cpan.org/ 

PLATFORMS 

As of version 5.002, Perl is built with a $^0 variable that 
indicates the operating system it was built on. Tins was 
irnplemcnLed to help S[)eed up code lliai woLiItl otherwise have 
to use Config and use the value of $Configk>snameh Of course, 
to get more detailed information ahoui tlie system, looking into 
^XConfig is ceitainly recommended. 

%Config cannot always he trusted, however* because it was 
built at compile time. If perl was built in one place, then 
transferred elsewhere, some values may be wrong. The values 
may even have been edited after the fact, 

Unix 

Perl works on a bew'iidering variety of Unix and Unixdike 
platforms (see e.g. most of the files in the hints/ directory in the 
source code kit). On most of tliese systems, the value of 
(hence $Configl'osname1, loo) is determined either by 
lowercasing and stripping punctuation from the first field of the 
string returned by typing imame -a (or a similar command) at the 
.shell prom pi or by ic.sting the file sy.stem for the presence of 
Linitjucly named files such us a kernel or header file. Here, for 
example, are a few of the more popular Unix flavors: 


aname 

$*0 

$Config{ ^archn:ame’ 1 

AIX 

aix 

aix 

BSD/OS 


i3S6-bs£los 

Darvin 

darwiti 

darwia 

dgux 

dgUK 

AViION dgux 

DYWTX/ptx 

dynixptx 

1386-dynlxptx 

FreeBSD 

freebsd 

treebsd 13B6 

LinuK 

linux 

aritt-linux 


Li nux 

1 i nux 

13S6-linux 

Li riux 

li mux 

i586-11nux 

Linux 

litiux 

ppc linux 

HP-UX 

hpux 

PA-MSClri 

IKIX 

Irix 

irix 

Mae OS X 

darwin 

darvin 

MachTen PPC 

coach ten 

poverpc-machten 

NeXT 3 

next 

next-fat 

NeXT 4 

next 

OmSTEP-Macb 

openbsd 

openbsd 

1386-openbsd 

OSFl 

dec_osf 

alpha-dsc_os£ 

celiantunix'n 

svr4 

RM400-svr4 

SCO sv 

sco_sv 

i386-SGO_sv 

SIHIX-N 

svr4 

RH400-svr4 

nn4609 

unicoH 

CRAY C90-unlcos 

sn6521 

unicosBik 

t3e-unicoanik 

sn96],7 

unicos 

CRAY_j90-uni[:cis 

SunOS 

Solaris 

sun4 Solaris 

SunOS 

Solaris 

i86pc: Solaris 

SunOS4 

sunos 

sun4-sunos 


Because the value of $ Con figl archname I may depend on the 
hardware architecture, it can vary more than the value of $AO. 

DOS and Derivatives 

Perl has long been ported to intd-style microcomputers 
ninning under systems like PC-DOS, MS-DOS, OS/2, and mo^st 
Windows platforms you can bring yourself to mention (except 
for Windows CE, if you count that). Users familiar with 
COMMAND.COM or CMD.fXE style shells should be aware diat 
each t>f these file spedficaLions may have subtle differences: 

$filespecO “ "c:/foo/bar/file.txt^; 

SfllefspGcl = "c: WfooWbarWfile. txt": 

SfllGSpGc2 = 'c;\fooVbar\file.Txr*: 

$fil€spGc3 = 'c:\\roo\\b3r\\file.txt': 

System calls accept either / or V as the path separator 
However, many comma nddine utililics of DOS vintage treat / as 
the optiort prefix, so may get confused by filenames containing 
/. Aside from calling any external programs, / will w^ork just fine, 
and probably belter, as it is more consistent with fx)pular usage, 
and avt)ids tlie [:)rcjhleiii of remeiiiberiiig what to backwhack and 
what not to. 

The DOS FAT filesystem can accommodate only '"8.3" style 
filenames. Under tlie "ca.se-insensitive, but case-preserving'' 
JJPfS (OS/2) and NTFS (Nl ) file,system.s you may have to be 
careful about case returned w'ith functions like readdir or u.sed 
with functions like open oropendir. 

DOS also treat.s several filenames as special, such as ALfX, 
PUN, NLIL, CON, COMl, LPTl, LPT2, etc, Unforlunalely, 
sometimes these filenames won't even work if you include an 
explicit directory prefix. It is best to avoid such filenames, if you 
want your code to lie portable to DOS and its derivatives. It's 
hard to know what these all are, unfortimately. 

Users of these 0 [)erating systems may also wish to make use 
of scripts such as [>12bat.bat or plZcmd to put wrappers around 
your scripts. 

Newline (\n) is translated as \015\012 by STDIO when 
reading from and writing to files (see Newline.s). 
binniode{FILEIlANDLB) will keep \n translated as \ 012 for that 
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fileiiandle. Since it is a no-op on other systems, hiiimode slionld 
be used for cross-platform code that deals with binary data. 
That’s assuming you reali;^e in advance that your data is in 
binary. Generahpuqxxso programs should often assume nothing 
about their data. 

The $^0 variable and the JSConfiglarchnamel values for 
various DOS is h peris are as follows: 


GS 


ro 

$ConfigInrehname1 

ID 

Version 

ME-IKJS 


dos 




PC-DOS 


dos 

7 



OS/2 


os 2 

? 



Windows 


? 

? 

0 

3 0] 

Windows 

95 

HSWin32 

MSWin32-3cS6 

1 

4 00 

Windows 

98 

HSWin32 

HSWin32-x36 

1 

4 10 

Windows 

HE 

MSWin32 

HSWin32-x85 

1 

7 

Windows 

NT 

MSWin32 

MSWin32-x36 

2 

4 XX 

Windows 

NT 

MSWin32 

MSWin32-ALPHA 

2 

4 XX 

Windows 

NT 

HKWin32 

MSWin32-ppc 

2 

4 XK 

Windows 

2000 

MEWtn32 

MSWin32 x86 

2 

5 XX 

Windows 

xt> 

HSWin32 

MSWiii32 xH6 

2 

? 

Windows 

CK 

MSWin32 

? 

3 


Cyswin 


cygwin 

7 




'I he various MSWiii32 PeiTs can distinguish the OvS they are 
running on via the value of the fifth element of the list returned 
from Win32::GetOSVcTsion(X For example: 

if (^^0 eq ‘MSWin32’) I 

my @os_version_ififo = Win32: :GetOSVersiont): 
print t( ■ 3.1 ', *95'/NT*) f$o^ verslcn_infQr9] ] ; 

1 

There arc also Win32::rsWinNT() and Win32::lsWin95(X try 
pcrldcK \X^n32, and as of iibwin32 0.19 (not part of the core Perl 
disiribution) Win32: :GetOSNanieO. I’he very portable 
POSrX::uname() will work tfx): 

ci\> perl 'MPOSIX 'we "print join '[*. uname** 

WIndovfi NT|ra{>onru| 5 .n|Rn i Id 2195 (Sc^rvtci^ Tack 7.) | K8f5 

Also see: 

The djgpp environment for DOS, 
hUp:/Avww.delorie.com/djgpp/and the perldos manpage. 

The EMX environment for DOS, OS/2, etc. einx@iachv.nl, 
http://wwTAcleo. org/pub/coinp/os/os2/leo/gnu/emx-i-gcc/index. 
html or ftp://hobhes.nmsu.edu/pub/a,s2/dev/emx/ Also the 
perlosZ man page. 

Build instructions for Win32 in the perlwin32 imnpage, or 
under the Cygnus environment in the perkygwin man page. 

The Win32::’^ modules in the Win32 man page. 

The ActiveState Pages, http://www.activestate.com/ 

The Cygwin environment for Win32; RFiADMK.cygwin 
(installed as the pcrlcygwin man page), http://www.cygwin.com/ 
The U/WIN environment for Win32, 
http://www.research.att.com/sw/tools/uwin/ 

Build instruction.s for OS/2, the perlos2 manpage 


Email software for Windows and Mac OS 
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Mac OS 

Any module requirinj^ XS cotnpiblion Ls riglu out ft>r most 
pcofjlc, [jccause MacPerl is built using non-free (and non- 
cheap!) conipilers. Some XS modules that can work with 
MacPerl are built and distrihuied in binary Fonn on CPAN. 
Directories are specil'ied as: 


voiime: folder r file 
volume:folder: 

1 folder:file 
: folder: 

:filo 

file 


for absoluite patimatnes 
for absolute pathnames 
for relative pathnames 
for relative pathnames 
for relative pathnames 
for relative pathnames 


MacPerl DevelopmenL, htlp://devjnacpCTLorg/ . 

The MacPerl Pages, http;//wwl^MTlacperl.conl/ . 

1he MacPerl mailing lists, littp://ILsLs.perl.c>i^ . 

VMS 

Perl on VMS is discussed in the perlvms inanpage in the 
perl distribution. Perl cm VMS can accept eitlicr VMS- or Unix- 
sly le file sfiecinc^ations as in ciLlier of the following: 

$ perl -ne “print if /peri_Eetiip/i" SIfS$L0C1H:L0C1N.COM 
$ perl -ne “print if /peri_aetiip/l'’ /sya$login/login.com 


Files are stored in the directory in alphabetical order. 
l■ile^ames are limited to 3l characters, and may Indude any 
character except For null and which is reserved as Llic path 
sciiarator. 

Instead of flcK'k, see FSpSetFLcjck and FSpRstFixKk in the 
Mac::Files module, or chmf.xi(0444^.. J and chmod(0666, .. J. 

In the MacPerl apjilication, you can't run a program from the 
comniitnd line; programs that expect @ARGV to lie populated can 
edited with something like the following, which brings up a 
dialog lx)x asking for the command line atgumenls. 

if ( IMRGV) [ 

@ARGV = split MacPerl::Ask{'Arguments?: 

I 

A MacPerl script saved as a "droplet’' will populate @AKGV 
with the full pathnaines of the Files dropped onto the scrip!. 

Mac users can run prognuiis under a type of commanti line 
interface under MPW (Macintosh Programmer’s Wcjrkshop, a free 
development environmeni from Apple). MacPerl was first 
introduced as an MPW tool, and MPW can lie used like a shell: 

perl myscrlpt.plx some arguments 

ToolServer i.s another dpp from Apple that provides access 
to Mi^W tools From MPW and the MacPerl app, which allows 
MacPerl programs to use system, backticks, and piped open. 

"Mac OS'' is the profier name for the operating system, but 
the value in Saq is "MacOS'k lb determine architecture, 
version, or whether the application or MPW tool version i.s 
running, check: 

Sis_app ^ SMaePeri:;Version /App/: 

$is tool = $MacPerl::Version /MPW/: 

{$version) = SMatPerl:iVerfilun ^ /^{\S+)/: 

$is„ppe $MacPorl: :Arcli irecture eq 'HacPPC'; 

$is_6ek = $MacPerl: :Arcli I lecturo eq ; 

Mac OS X, irased on NeXT’s OpenSle[i OS, runs MacPerl 
natively, under the ^"Classic” environmeni. I'here is no 
^Xarbon" version of MacPerl to run under the primary Mac OS 
X environment Mac OS X and its 0[>cn Source version, Darwin, 
both run Unix perl natively. 

Also see: 


but not a mixture of both as in: 

$ perl nc ''print If /perl_.‘?etup/i“ sys$logln:/login.com 
Can't open sys$log!n;/login. cobi: file specification syntax 
Error 

Interacting with Perl from tiie Digital Command Unguage 
(DCL) shell often requires a different set of quotation marks than 
Unix shells do. For example: 

$ perl -e “print “"^l^^^o, world An""” 

Hello, world. 

There are several way.s to wrap your fieri scripts in DCL 
.COM files, if you are so inclined. For example: 

S write sys$output “Nelio from DCLl" 

$ if pi .eqs. ““ 

$ then perl -x 'fSenvironment(“PROCXDURE") 

$ else perl -x - ‘pi ‘p2 'p3 'p4 ‘p5 'pfi 'p? 'pS 
$ deck/dollarR=“_™_“ 
til /usr/bin/perl 

print "‘Mello from Perlt\Ti”; 

. END 
$ endif 

Do lake care with $ ASSIGN/nolog/iiser SYS$COMMAND: 
SYS$INPUT if your perl-in-DCL script expects to do things like 
$read - <STDIN>;. 

Filenames are in I he formal Tiame.extension; veision'\ The 
maximum length for filenames is 39 characters, and the 
maximum length f<ir exteasions Is als{) 39 characters. Version is 
a numlier from i U> 32767. Valid characters are /IA-Z0-9$_'1/. 

VMS's RMS filesystem is case-insensitive and does not 
preserve case, readdir returns lowercased filenames, l)ut 
specifying a File for ojxming remains case-insensitive. Files 
without extensions have a tniiling period on them, so doing a 
readdir with a file named A.;5 will return a. (though that file 
could be opened with open(FH, 'A')). 

RMS had an eight level limit on directory depths from any 
rooted logical (allowing 16 levels overall) prior to VMS 7.2. 
lienee PERL^ROOT:111R.2.3-*^ 5 6.7.81 i.s a valid directory 
spccificati()n but PERL_ROOT:[LIB.2.3.4.5.6,7.83;l is not. 
Makefiie.PL authors might have to take this into account, but at 
least they can refer to the former as 
/PFRr.^ROOT/lil)/2/3/4/5/6/7/8/. 

The VMS::Fiiesjiec module, which gets installed as part of 
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the hiiilcl process on VMS^ Ls a pure Perl module lliat am easily 
insialled <jn non-VMS platforms and can lie helpful for 
conversions to and from RMS native formats. 

What \n represents depends on the tyjie of hie opened. It 
usually represents \012 but it could also be \0J5, \012, 
\015\0!2, \(H)0, MHO, or nothinj^ depending on the file 
organization and record format. Tlie VMS-Stdio mtxliile 
provides access to the special fopenO requirements of files with 
unusual attributes on VMS. 

'fCP/lP stacks are optional on VMS, so s(K:ket routines 
might not be implemented. LJDP sockets may not be supfxirted. 

Tile value of $AO on OpenVMS isVMS". To determine the 
architecture that you are running on witliout resorting to loading 
all of %Contig you can examine the content of the @HNC array 
like stx 

if (Rrep(/VMS_AXP/. eiNC)) t 
print "I'm on Alpha I\n*; 

I elslf (grep{/VMS_VAX/. §1NC)) [ 
print "I’m on VAXiVn": 

I else t 

print "Vn not so sure about vbere 

1 

On VMS, Perl determines ihe UTC offset from the 
SYS$'l'lMEZONi:J.>IFIT:RI’:NnAL logical name. Although the 
VMS eptK'h began at 17-NOV-18S8 00:00:00.00, calls to localtime 
are adjiLsted to auinl offsets from 01-JAN-1970 00:00:00.(X), just 
like Unix. 

Also see: 

README.vms (installed as ltEADME_vms), the perlvins 
manpage 

vmsperl list, majordoino@per).org 
(Put the words subscTilie vmsperl in message IxxjyJ 
viiKsper! on the w'eb, 

http://www^sidhe.QIg/v^lsJ>e^l/index.hUnl 

VOS 

Perl on VOS is disacsscd in README.vos in the Perl 
distribution (installed as the perivos manfiage). Perl on VOS <^an 
accept either VOS- or llntx-style file speci 11 rations as in either of 
tlie following: 

C« $ peri -ne "print if /perl setup/r' >Kyst(»ra>nf)t icoa » 

C« $ perl -ne "print if /perl_Bettip/i" /ByBtnm/notices » 

or even a juixture of Ixjth as in: 

C« S pt'rl ne "print if /perl_setup/i" > system/not ices » 

Even though VOS alk>w.s the .slash chanicter to appear in 
objea names, lx:aiuse the VOS port of Perl intejprets it as a 
ptirhname delimiting character, VOS files, diredories, or links 
whose names contain a slash character cannot prexessed. 
Such files must lx: renamed l^efore tliey can 1^ processed by 
Perl. Note that VOS limits file names to 32 or fewer characters. 


Perl t)n VOS can be btiilt using two different compilers and 
two different versions of the POSTX nintime. The recommended 
method for building fuU Perl Ls with tlie GNl) C compiler and the 
generally available version of VOS POSDC suppon. See 
README.vas (installed as the perivos manpage) for restrictions 
that apply w^hen Perl is built using the VOS Standard C compiler 
or the alpha version of VOS POSIX support. 

Tlie value of $ao on VOS is "“VOS". To determine the 
aicliitecture tliat you are ainning on without resorting to loading all 
of %Config you can examine the content of die ©INC array like so: 

if {$^0 =- /VOS/) [ 

print “I'm on a Stratus boxl\n“: 

] else I 

print "I'm not on a Stratus faoxDn"; 
die; 

I 

If EErep(/860/. 8TNC)) I 

print "This box Is a Stratus XA/R!\n": 

I elstf (grept/nOO/. #INC)) I 

print "This box is a Stratus HP 7100 or 8xxx!\n": 

I elsif (6rep(/&000/, #INC)) I 

print ■'This box Ls a Stratus HP SxxxDn'*: 

I else t 

print "This box is a Stratus 68K!\n": 

I 

Also see: 

README.vos (installed as the perivos manpage) 

The VOS imiling list. 

I here is no specific mailing list for Perl on VOS. You can post 
c'ommenLs to the comp.sy.s.stratus newsgroup, or suhscrilx* to tlie 
general Stratus mailing list. Send a letter vvith "'subscribe Inlb- 
Straius" in die message Ixxly to maH>rdomt>©lisL..HLmtagyx-om. 

VOS Perl on the web at 

rjUp://ftp.smmts.corn/ptib/vcxs/p(>six/ixisix.himl 

EBCDIC Platforms 

Recenl versions of Perl have Ix^en ported lo platforms such 
as OS/'1(X) on AS/4()0 mtnict>niputers as well as OS/390, VM/ESA, 
and BS2000 for S/390 Mainframes. Such comfxileni use EBCDIC 
chantaer sets internally (usually Character Qxle Set ID 0037 for 
OS/KX) and either 1047 or P()SIX-B(.' for S/390 systems). On the 
mainframe jierl eunreniiy wtirks under the "Ifnix system services 
for 08/390" (formerly known as OpeiiEdition), VM/ESA 
OpenEditJon, or the BS2tK) POSIX-BC .system (B82000 is 
supjxjrted iti jx^rl 5.6 and greater). See the perlcxs390 manpage for 
details. Note that for OS/400 there is alst) a port of Peri 5.8.1/5.9.0 
or later lo ihe P/LSE which is ASCI I-based (as opposcfl to HE 
which IS EBCDIC-based), see the perltxs400 manp^ige. 

As of R2.5 of USS for 08/390 and Version 2.3 of VM/RSA 
the.se Unix sub-systems d<] not supiXJit the shebang trick for 
script inv(xalif>n. Hence, on OS/390 and VM/ESA |ierl sciipts ctin 
be executed with a heiider similar to the following simple script: 

: # use perl 

eval 'exec /usr/local/bin/perl -S $0 
if 0: 

#1/usr/local/bin/perl I Just u coomcnl really 

print ■‘Hello frotn perlUti": 
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OS/390 will suppon ihe shcl>Luig trick in release ajid 
l^eyond. Calls it> system and backticks can yse POSLX shell 
syntax on all S/390 systems. 

On the AS/400, if PHItL5 Is in y<Hir lilimry list, ytju may need 
to wrap your perl -scripts in a CL f)rtx:edure to invoke tliem like so; 

BEGIN 

CALL PGH(PKRLWFEHL) PARH{ ‘/QOpenSys/hfiilo^pl ’) 

ENDPGH 

This will invoke the perl script hello,pi in the root of tlie 
QOpenSys file system. On iliu AS/'lOO calls to sysiem or 
backticks mtist ilsc CL syntax. 

On lliese |)latibrins. I>eur in mind that the EBCDIC chamclcr 
set may have an effect on what happens with some [KtI 
functions (snc'h as chr, puck, print, printf, ord, sort, sprinif, 
unpack), as well as bit-fiddling witli ASCII constants using 
operators like a, ^ and noi to mention dealing with socket 
interface.s to ASCII computers (see Newlines). 

Foniinately, most web servers for tlie mainfii^me will comectly 
translate the \n in the following statement to its ASCII a|uivatent 
(\r is the siime under ixxh Unix and OS/590 & VWESA): 

print “Content type; texT/hrnil\r\n\r\n''; 

rhe values of on some of these platforms includes: 




SConfif^ I' archname ' I 


OS/390 os390 051390 

03400 os400 O514D0 

POSIX-BC poaix be BS^OOO ponix-bc 

VM/ESA vmeaa vmesa 

Some simple iricks for ticleniiining if you are ainning on an 
EBCDIC platfonn could include any of the following (perhaps all); 

if {“Vt" eq I print “EfiCDTC may be jspoken herelVn": I 

if (ord{‘A*) “ 193) 1 print “EBCDIC may be spoken hcrclXn": I 

if (chr(169) cq *?/) I print “EBCDIC nay be spoken herE!\n“r I 

One thing you may not want to rely on is the EBCDIC 

encoding of punctuation charatlers since tliese may differ fram 
code page U) ctxle page (and once ycjur mtxlule or script is 
niinored to work with EBCDIC, folks will want it to work with 
all EBCDIC character -sets). 

Also see: 

Tlic perlos390 manpage, RHADME,os39d. perlhs2000, 
README vmesa, the perleixdic man page. 

The perl-mv.s@pcrLorg list is for discussion of porting issues 
as well as general usage issues for all EBCDIC Peris. Send a 
niesSsage IxxJy of'"sui^scrilx? perl-mvs'' to maiordom(3@jx:rl.org, 

AS/400 Perl information at iiup://as400.rochesteribm.com/ 
as well as tm CPAN in the ports/ directory. 
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PERL BASICS 


hy Paul Ammann 

Opening Things in Perl 


Perl lia,s two simple, l)uill-in ways to open files; the shell way 
for cx^nvenienc-e, and the C way for precision. Tlic shell ways also 
liits 2- aixi 3-ar^^umenr Ibrms, which liave different .seimntics for 
Itandling the file name, Tlie (’lioice is yoiirs. 

1* Open A ia sohl 

Peri s open hmtiion was designed to mimic tlie way command- 
line redirection in the shell works. Here are some Imic examples 
from the shell: 

$ myprograni tiiel fileZ fil£3 

$ royprogrant < inputfile 

$ fflyprogram > mitputftie 

$ myprogram » ouiputflle 

S myprogrnm ] oiherprogram 

$ otherprograiD | rnyprograni 

And here are some more advanced examples: 

S otherprogram | myprogram fl - f? 

S otherprogram 2>il | myprogram 
$ myprograiii 
$ Hiyprogram >Si4 

Programmers accustomed to coiistructs like tliosc* alx>ve c;m 
take a)mf(>rT in learning dial Perl directly supjxjns these familiar 
ajasimcis using virtually die same syntax as the shell. 

1.1 Stniplc Opens 

Hr.- opc:n funiiion rakes two arguments: die first Is a fileliandle, 
and die scx’ond is a single string ajmprising both what to open and 
how to ojx^n it. open aiiims inie when il works, and when it fails, 
returns a false value and sets the special variable $! to R^fiecl the 
sy^'^em error If the filehandle was previously opentxl, it will lie 
implicitly dosed first. 

For crxiimple: 

open (INFO, ■'datafile'') || dieC-can/t open datafile: 
open (INFO* ”< datafile^) M diep'can't open datafiloi $!“); 

open {RESULTS *“> runatata*') |f dle('*can't open runatata: SD? 

open (LOG/'» logftle ") || die("can't open logfile: $!"); 

If you prefer die low-punctiuilion version, you could write thn 
this way: 

open INFO, “< datafile" or die "can*t open data file: $!"; 

open RESULTS. "> rtjnatats" or die "caii*! open tanfJtats: St"; 

open liOG,"» logfilo " Ot die "can't open logfile: $!": 

A few things to rKMict:, First, the leading less*dian us optional. If 
omittcxl, Peri assumes iliat you want to open the file for recidmg. 

Note also thiit die first example uses die 11 logk:^il operator, 
and the second uses or, which has lower precedence. Using 11 in 
the latter examples w'ovild effectively mean 


open INFO, ( datafile*' || dlc "caiCl apeu datafile: $!" }; 

which Is definitely not what you want. 

Tlie other tnifxirtant dang to notice is that, jiisl as in the sliell, 
any while space liefoiv or after die filc^niime is ignored. Tills Ls gtxxJ, 
Ixx-atLse you wouldn’t want these Co do diffwnt diin^: 

open LNli}* "<datafiie" 

open INFO, "C datafile" 

open IHFO, "< datafile" 

IgiKiring ,sunx)unding whitesjxrce also hdfw for when you read 
a filcTiame in frenn a diffeienl file, and luigcl to trim it liefore 
ofiening: 

$fiitniatiie = ClNFO): # oops* \n $tili there 

opei](EXTRA, "< $filename") || die "can't open SfilenaiciG: $!"; 

Tills is not a bug, but a Ibirurc. IteTiuse oixn mimics the sliell 
in its .style of using redirection arrows to sjxxlfy liosv to open tlie file, 
it ak) does so witli lesjiect to extra white spaa.* around die filename 
itself as well. For aireastng files with nauglity namt^s, see DLsjxTling 
die Dweomer 

Tiiecv is also a ^-atguiiienl version of open, which leLs you put 
tlie special ledimdion cliaracters jjito their own argument: 



In dlls case, the filename to ojx^n Is the adiuil ^mlng in $datafile, 
sf) you don't have to worry alxHtt $dalafile ainiaining chameters that 
might influence" the o[ien nxxle, or whitespace at die fieginning of 
the filename that would lie alisnrlietl in the 2-aigiimeni version. Also* 
any reduction of unnecessary siring inteipolation is a good tiling, 

1.2 Indirect Ftleliandles 

o[R‘n'.s first atgumeni can lie a Reference to a fileliandle. li‘ the 
aigumeni Ls uninitialized, Peri will aulornaiically create a filehandle 
and put a relerenc'e to it in the first argmnent. like so: 

opent toy $in* $infile ) or die "Couldn't ™d $ infile: $t"; 
wMle ( <$in> ) I 

If do soaething with $_ 

I 

close Sim 

Inditect filehandles make naiiiesiiace management easier Since 
fiiehandles are glolxil to the CTirrent jxickage, two sulinxilines trying 
to open INRLH will clash. With two hinctions opening indirect 
fileliandles like my Sinfile, there’s no clash and no need to worry 
alxiut future conflicts. 
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Another t:onvenicnl lx.‘iravi(r is ihat an inclirett Hlehandle 
autoimtically doses when it gtjes out of sajf>e or when you 
undefine It: 

sub firstling [ 

open{ my Sin, Btdft ) rgrurn scalar <$in>; 
f no closet] required 

] 

1.3 Pipe Opens 

In C, wlien you want to open a file using the standard I/O 
lil^niry, you use the fopen fiinaion, hui when opening a pipe^ you 
use the popen function. But in llie shell, you just use a different 
rediieetion character Tliafs also tile case for Perl The ojK^n call 
a-inains the same-just its afgun’ient diffm. 

It the leading chanider Ls a pipe symbol^ open starts up a new 
c^inunancl and opens a write-only llleliandle leading into that 
coiTunand. 'Ihis lets you write into that handle and have wliat you 
write show np on that command’s .standard input. For example: 

opeD(PKlNl'ER. Ipr -Plpl") 11 die "can't run Ipr; $1": 
print PRINTER "stuff\n": 

close(PRINTER) || die “can't close Ipr: $!": 

If the trailing diaracier is a pi[:)e, you start Lip a new command 
and open a read-<aiily filelitmdle leading out of that cxjoiimmd. Hus 
lets whatever tliat LX>mmantl writ(‘S tt) its standard output show up 
on your iKincDe for reading. For exiiinfile: 

open (NET, "netstat i n ]'')|| die “can't forJ^ netstat: SP; 
while (<NET>] \ 1 # do somoLhlng with input 

clQSG(NtT) II die “can't close netstat: $!": 

What happens if you try to open a pipe to or froni a non¬ 
existent t’ommand? If possible, Perl will detect the failure and set $1 
as usuaL Bui if tiie command contains stxx:ial shell charaticrs, sueii 
as > or called 'ineUichiracters', Perl does ncM execute tlie 
atmmand directly. Insteiid, Perl runs the shell, wliicli then tries to 
run llie command. Tills means that ifs the shell that gets the emir 
indication. In such a case, the 0|5en call will only indicate failure if 
PeH ain't even mn the shell. 

1.4 Tlie Minus File 

Again ibllowing die lead of the standard shell utilities, Perl’s 
ofKii function ireais a file wliose name is a single minus, in a 
sjxxial way. If you ojien minus for reading, it really means to access 
the standard input. If you open minus for writing, it really means to 
access die standard oniput. 

If minus can l>e used as tlie default input or default output, 
what happc*as if you opi^n a pipe into or out of minus? What’s tfie 
dtdaiili command ii W'oulcl mn? Hie s;iine .scTipt a.s you’ie curraitly 
running! TliLs is aciually a stcalili fork hidden inside an ojien call. 

1.5 Mixing Reads and Writer 

It is possible to sp^ecify Ixith read and write acx’ess. M you do 
is add a symlxil in front of the redirecnion, Bui as in tfie shell, 
using a less-than on a file never creates a new file- it only opens ;m 
existing one. On the other hand, using a greater-than always 
clobliers (truncates to zem lenglli) an existing file, or creates a 


bntnd-new one if there isn’t an old one. Adding a “+Tor ratci-write 
dtxrsn’L affc-ci whedier it only works on existing files or always 
clobl:>ers existing ones. 

open(WTMP, “+< Aisr/adtii/wtfnp“) 

IJ die "can't open /nsr/adm/wtrap; Sf*; 
open (screen* ■‘+> /tmp/lkscreen’') 

I I die "can't open /impyikscreen: $1'’: 
open(LOClTLE* “+» /tmp/appiog" 

I I die "can't open /tmp/apploft: S!": 

Ihe first one won’t create a new file, and tlie second one will 
always clobber an old one. llie third one will create a new file il' 
ncccs^sary and not clol)i)cr an oki one, and it will allow you to read 
at any point in tlie file, liut all writes will always go to die end. In 
short, the first case is sulistantially more common than the second 
and ihial cases, which are almo.st always wrong. (If you know C, the 
plus ill PerPs open Ls liistorically derived from die one in Cs 
l:bpen(3S), which it iiltiniateiy calk.) 

In fart, when it rt>mes to updating a file, unless you're working 
on a binary file us in die WTMP case above, you probably don't 
want to use diis appnxich for ujxiating. Instead, Peri’s T flag comes 
lo the resale. Tlie following command lakes all the C, C++, or yacc 
source or header files and changes all tlieir foo’s to bar’s, leaving the 
old version in the <iriginal filename with a ".orig" tacked on the end: 

S perl -l.orlg -pG 'fi/\bfoo\b/bar/g' . [Cchy] 

Tliis IS a slion cut for some renaming g£imt:s that are really the 
best way to iijxlate texifiles. 

1.6 Fillers 

One of tile mcjst comiiion uses for ojx:n is [>nc you never even 
nodee. When you process the ARGV fileliandle using <ARGV>, Perl 
actually dexis an implit'ii open on e;ich file in @AJCrV. Thus a 
pnigrani aiUed like diis: 

$ [jiyprograin flle2 filc3 

Can iiave all iLs files opened and prcx:essed one at a time using 
a coastruct no more complex than: 

while (O) [ 

# do something with 

I 

If @ARGV is empty when the loop first begins, Perl pretends 
youVe opened up niinas, ihtt k, die siundaiil input. In fact, $AKGV, 
the cufcently open file during <ARGV> proce,ssiiig, is even set to 
“ in these dnaiinstances. 

You are welcome to pm-pnK'e,s.s your ©ARGV lx.‘fom .starting 
the loop to make sure it’s to your liking. One reason to do diis might 
be to remove cximmand options lieginning widi a tiiinus. WliiJe you 
can always roll die simple ones l>y fiand, the GetopLs mcxlulex are: 
good for diLs: 

use Getopr::Std: 

-V, -n, -0 ARG* sets $opL_v, $oplJ), $opt_o 
gctopts(''vDcir''); 

# -V* -D. -a ARC. sets $argslvt, SargslDL $argslnl 
getopt s("vDo:”. \%ar gs]: 
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Or tlie standard nuxliile to named 

arj^uments; 

use Cetopt: : 

GeiOptlotist ''vetboso" V$verboee,# --verbose 
*Debug''*> \$debag* § -mebug 
"output's" '> \$output 

tf --OUtput=s aide St ring or ’-output soiftestring 

Another reason for prepixK:essing aigiiinenis is to iitike an 
empty arguinent list default to ;il! files: 

SARGV - globi"*") unless @ARGVr 

You could even filter out *ill Ixit pkin, text files, Ttiis is a l>it 
silcmi, of course, and you might preft^r to mcmUt jn tlian on the way. 

#AHGV ^ grep [ -f M T t @ARGV: 

ff you're using the -n t^r -p cxminiand-line options, you should 
put changes to ® ARGV in a BEGINII blot'k. 

RcmLinlx.T tliat a normal open has special piofx'fties, in that it 
niiglit call fbpen(5S) or it might called fx>jx^n(3S), depending on 
what its aigumenr looks like; that’s why it’s sometimes cilled ''magic 
open". Here's an example: 

$pwdinfD “ 'domaiuname' /''t\(nonc\))?$/ 

? ■< /etc/passvd* 

; 'ypcat passwd \'i 

open(PWJ], $pwtliiifo) 

or die "can't open $pwdlnfo: $}”; 

Tilts sort of tiling also comes into play in filter pitKessing. 
IkxxiLise <ARGV> processing employs tlie nonnal. shell-style Perl 
open, it respeas all the special tlriiigs we’ve already seen: 

S nyprograa fl "cmdll" - f2 “CB»d2|" £3 < tinpfiile 


Tliat prognim wdl read from the file fl, tiie j>rocess cnxll, 
standard input (tmpfile in ihis case), tlie f2 file, the cmd2 command, 
and firuilly the 6 file. 

Yes, tills 2 tLso meaas that if you have files named (and .so on) 
in your directory, they won't Ix! prtxessed as liteml files by open. 
You’ll nmi to pass tliem as much as you would for die mi 
program, or you could use sysopen as de-scrilxxl Mow. 

One of the more interesting applicatititis Is to change files of a 
certain naiiK" mxo pipes. For example, to aiitoprocess gzipjxxl or 
aimpresstxl files liy dcxximpressing them with gzip: 

MRGV " map I /^\.(g2|2}$/ ? "g^lp dr |$ I @ARGV: 

Or, if you liave the GiiT program iasialled from LWP, you can 
felcli URLs Ix^foro protx^ssing them: 

^ARGV - map i 7 XET : $_ i ^AKGV; 

It's not for nfXhing it tat tills is cxillc^l magic <ARGV>. I^relly 
nifty, eh? 

2- OPliN A lA C 

Lf^ y(Hi want tlie ainvenience of the sliell, then Perf s o|x.m is 
definitely tlie way to go. On file other hand, if you want finer 
f^sedsion than Cs simplistic fopen(.iS) provides you should lfx>k to 
Perl’s sysopen, whidi is a direct hook into the open(2) system aill 
Tliat dex-s mean it’s a bit more involved, but that's tlie price of 
prtxision, 

sy.*;op(»n takes 3 (or 4) argLotietitg. 
syiJopecv RANDt.E, PATH. FLAGS. [HASK] 
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'rhe [ lANDLI: argumeni \s a filehandle just as with open. The 
PATH is a litei'al path, one that doesn’t pay alleniion to any 
grealer-lhans or less-ihaas or pipes or minuses, nor ignore white 
space. If it's tliere, iPs part of the path, I’he FLAGS ai^unient 
contains one or more valuers derived from tlie Ft ntl nxxiiile that 
have been or’d together using the bitwise “|” openiior. The final 
argument, the MASK, is optional; if present, it is coinbined vviili 
the user’s current umask for die cxcation mode of the file. You 
siioukl iisttally omit iliis. 

AltJiougli tlic traditional values of read-only, wriie-only, and 
read-write are 0, 1, ^md 2 respectively, iliis i,s known ncx to hold tnie 
on some Ksystertis. lastead, ifs test to load in the appropriate 
constants fiisi fixHn the FentI module, wdiicli supplies die following 
standard flags: 

0_ltnONL¥ Read only 

C]_WR0NL¥ Write only 

O^RBWR Read and write 

Q_CREAT Create the file if It doesn't exist 

0_EXCL Fatl if the file already exists 

Q„APPEtn3 Append to the file 

0 TKtJNC Truncate the tile 

0. NGNBliOCK Non blocking access 

Less common Hags that are sometimes available on some 
operating systems include 0_B1NARY, 0_'rbXi; O^SHLOCK, 
Q_EX1.0CK, 0_DEFER, Q^SYNC, O^ASYNC, O.DSYNC, 
Q_RSYNC, 0_N0CrrY, O^N DELAY and 0_LARGEF1LE. 
Consult your open(2) man page or its local equivalent lor 
details. (Note; As of Perl release 5.6 tiie OJ.ARGKFILE flag, if 
available, is auiomatic’^illy a tided to the sysofjenO flags because 
large files are llie default.) 

Here’s how to tuse sy.sopen lo emidate the .simple open calls we 
had IxrlbnLt We ll omit the | | die $! checks for tlarity, but make sure 
you always check the return values in leal cxxle. These aren't 
the siinie, .since cijxn will ijiin lending and trailing w'hite sfiace, but 
you ll get the idea, 

To open a file for reading: 

opentFH, '*< Spath’’); 
sysopenlFH, $path. OjavONLY): 

To (Jixai a Hie tt)r writing, pealing a new file it needed or else 
Lnmcaling an old Hie: 

open (PH, Spath"): 

sysopentFK. Sparh. 0_WR0HLY | 0„TRI!NC | O^CRKAT); 

'lb ofX'n a iile for nppcaiding, cTeaiing one if netx’ssary: 
opentFH, "» $path*'); 

sysopen(FH, $pnth. 0_Wk0NLY | O.APPEND | 0 GREAT): 

To open a hie for Lifxlaie, where! ilie hie must already exisi: 

open [Pit, "+< ^path"): 
sysopentFH, $patli, 0_RDWR); 


And here are things you can do witli sysopen Uiat you c:annot 
do with a regular open. As you'll see, ifs just a matter of contixjlling 
die flags in the tliird aigument. 

To open a file for writing, cieaiing a new file which must not 
previously exist: 

sysopejitFH, Jpath, Q WR0ra4Y | 0_EXCL | 0_CREAT): 

To open a file for appending, wliere that file must already exist: 

aysopentPH, $path. O_WR0NLY | 0 APPEND)^ 

lb open a file for ujxlate, creaiing a new file if necessary: 
i^yfiopentFN. $pcith, 0_RDWR | 0_CR£AT) : 

To open a file for update, wheie thai file must noi alrejidy exist: 

BysopeivtFH. $psth, 0_RDWR | 0_EXCL | 0_CREAT): 

To ot)en a file wiihout bkx'king, debiting one if necessary: 
sysopenCFH, Spath. 0_WK0NLY | 0_NaNBL0CK | O.CREAT) ; 


2,1 Permissioas a la mode 

If you omit the MASK aiguiiient tt> systipen, Fed uses the octal 
value 0666. The nonnal MASK to use for execuiabk's and directories 
should te" 0777, and for anyiliing dsc!, 0666, 

Wily so jxnnissive? Well, it isni regally. Hie MASK will he 
modified by your pixx'eas’s cunent umask. A umask is a number 
represctiling di,sai>kxl pemiLssk,>ns bits; that is, bits diat wiU not Ix! 
turned on in the creaied files' permissions field. 

For example, if your uma.sk were 027, then the 020 part would 
dkfole the gnxip fn>m writing, and the tX)7 p^ut would di.sable 
others from leading, writing, or executing. Under these conditions, 
passing sysopen 0666 would CTcale a file wiili mcxle 0640, since 
(Xi66 ik -027 is 0640. 

You should seldom use the MASK argument to sy,sojien(). 
'Ihaf takes away the user’s freedont to c hoo.se what permission 
new files will have. Denying choice is almost always a had thing. 
One exception woulcf be for cases where sensitive or private data 
is being stored, such as with mail folders, ccxikie files, and 
internal temponuy^ files. 

3- OiiscitRE Open Tricks 
3-1 RC'Opening Files (dups) 

Sonieiimes you aln^ady have a fileJiandle ojxrn, :uid v^'ani lo 
make anoflier Iiandle thafs a duplicate of tlie first one. In foe shelf 
we place an ampersand in front of a file descriptor number wlien 
doing tedireciions. For example, 2>^1 makes descriptor 2 (that’s 
S'lBERIi in Peri) lx: redirected into descriptor 1 (which is usually 
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Perl’s S'lIXJirr). llie same Ls essenlially true in Peri: a filename that 
begins wiih an ampc^rsand is ueated instead as a file descriptor if a 
numlx.Tt or as a filehandle if a 

OpenCSAVEOUT. ">^SAVEERR'*j || die "couldn't dup SAVKERR; $1"; 
open(MKCONTEXT. || die “cooldti't dup f(l4: $!"; 

'lliat means that if a fnntiion is expecting a filename, but you 
don't want to give it a filename Ix^cause you already have the file 
oj)en, you can jtiM pass tlie filehandle with a leading ampersand. It’s 
liest to use a fully qualified handle tliough, juM in cisc the function 
happens tt> Ix^ in a dilTeteni package: 

co[BGfun<rr.ionf''^[nain: : L 0 CFILE''): 

Tills way if somefuiiitionO is planning on opening its 
atgunK'iit, it ctin just use the already opentxl liandle. Tills diffcts 
from passing a handle, Ixaaase witli a liandle, you doivt 0 |xai the 
file. Here you liave .soniclliing you can p;iss to open. 

If you liave one of those tricky, neufangk^l I/O ol>jetis that ilie 
C++ folks are raving alxntt, then this d{x.-sn’l woric Ixxause tliose 
aren't a pnoptT filcliandk* in die ruitive Perl sense. Yoifll have to use 
filenoO U> f>ull out tlie proper descripior numl^r^ assuming you t:an: 

use 10::Socket; 

Shandle “ 10:: Socket:: INirr - >iieTi^Cww > perl. com; 80 “ J: 

$fd = $handIe‘>fiiervo: 

nomof(JTif‘tian{ "^iSfd’‘): # not an indirect imiction call 


with. In diis way, Perl is als o fiJIetl with dwcoiner, an t>l:)scure word 
meaning an enchantmcnL Sometimes, Peri’s llWlMmer is just too 
much like dwaimer for comfort. 

If magic open is a bit too miigiral ftrr you, y<Ri don’t have to 
turn to sysopen. To open a file witli arliiiraiy' weird cliaracters in it, 
it's oecc'ssary to j^roiect any kniding and trailing whitesp^ice. Ijeadtng 
whitespace is protected l>y inserting a **./'’ in front of a filename dial 
starts with whitespace. Trailing whitespace Is protected by 
appending an ASCII NUL byte (“XO”) at the etid of the string, 

$file — 

Gpnn(FHt "< $filo\0") || die “can't open $P: 

'Hiis itssumes, of’ axtrse, that yottr system <-onsiders dot the 
airreni working diretlory', slash die directory sefxtrator, and 
disallows ASCII NLILs witliin a valid fileniime. Most .s^'^stems follow 
these conventions, including all TOSIX systems as well as 
proprietary Microsoft systems. Tlie CMily vaguely |X)pular system that 
tkxtsn't work diis way Ls the proprietary Macintexsh system, which 
uses a colon wliere the rest of us use a sla.sh. Maylx: sysopirn Isn’t 
SLidi a ixid ide:t after all. 

If ycxi want to use <ARGV> prcrcessing in a icXally toring and 
non-magiciil way, you could do this first: 

f "Sam sat on the ground arid put hia ho^d in hia hands, 
i 'I vlsh I had never come here, and 1 doiC L want to nee 

I no more mgle/ he said, and fell sileriL.’* 


It can !x.‘ aisier (and certainly will lie fiister) just to tise real 
fileliandles though: 

use 10 ::Socket: 

local 'REMOTE = 10 ::Socket::im hiew(“WWW,|>crl.coin: 80 ”): 
die “can't connect" unless defined(fileno(REMOTE))i 
somefunction("Villain::REMOTE”): 

If die fiieliandle or dt^riptor numl^er is prec’eded n<x just witli 
a simple but nither with a t'ombinaiion, then IVri will mx 
LTe^rte a mmpkicly new tiescripior ofxaied to tlie same place using 
die dup(2) system fall, lasteiid, it will just make sometliing of an 
alias to the existing one using tlie fdopen(3S) library trail lliis Is 
slightly more p^irsimonious of .systems resources, :dtliough tills is less 
a concern these days. Here's an example of drat; 

$fd = $ENVrKHC0WTEXTFD” [: 

opcntMHCONTEXT. "<&-Sfd") or die “couldn't fdopen Sfd: $1": 

If you're using magic <AKGV>, you could even pass in 
as a command line argument in @ARGV something like 
'‘<&=$MHCONTFXTFD’*, but we've never seen anyone 
actually do tfiis. 

3-2 Dispelling the f>weo!iicT 

Peri is more of a DWIMiiier language tlian something like Java- 
-wliere DWM is an acionym for "do wliai 1 me;m’'. But this prirK:iple 
sometimes leads to more hidden magic than one knows wliat to do 
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for (®ARCT) I 

$_ .= no”; 

f 

while (<>) [ 

# now process $_ 

) 

Bill lx; warncxi dial u,ser5 will not appreciate \ie\ng unable to 
use to mean standard input, per the stancknd itinvention. 

3.3 I*aths ^ Opens 

YouVe probably noticed how Perl's warn and die Urnciions can 
prcxluce messages like: 

Some warning at scriptname Line 2 ^, <Fri> line 7. 

limit’s t)et:airse yoii opened a fileliandle FH, and had read in 
seven netxxds from it. But what was die name of the filCt Hither Ilian 
the handle? 

If you aren’t running with stria refs, or if you’ve turned them 
off temporarily^ llien all you have to do us tills: 

QpGn($patb, “< $path") || die “can't open $paih: $!": 
wfine ((SpattiV) \ 

II whatever 
I 

Since yoifre using tlie pathname of tlie file as its liimdle, you 11 
gel warnings tnoie like 

Some warning at scriptnanie line 29♦ </etc/motd) line 7. 

3.4 Single Argument Open 

Remember how we said that Perl’s open Icxik two aiguments? 
'lhat was a passive pnevariaition. You see, it can also take just one 
argument. If and only il'ilie variable is a global variable, no! a lexiail, 
you am pass oiien just one argument, the liiehandle, and it will get 
the p:Uh from the globil .sc alar variable of the same name. 

SFFIjK -/etc/tnotd'*: 

opGii FILE or die “can't open $FILEi $!“: 
while (<F1LE» I 
// whatever 

f 

Why is this here? Sotneone has to cater to Uie hysterical 
porpoi,ses. It's .something iliat's lieen in Perl since the very 
ix*gi!ining, if not lx;foie, 

3.5 Playing with SIDIN and STDOUT 

One clever move with STDOIJT is to exjilicitly dose it when 
yoifre done with the program. 

liND I cloi,-*(STDOUT) || die “can't cloae stdout: $['’ I 

If you don1 do this, and your prx>gram fills up die disk panition 
due to a command line redirection, it won’t rqxirt the eiTor exit widi 
a failure sUitus. 


You don't liave to accept the Sl'DlN and S'l DOU r you wem 
given. You are welcome to reopen them if you’d like 

openOTDIN. “< datafile") 

1] die “can't open datafile; 
opentSTOCUT. “> output") 

II die “can't open output: $ 1 "; 

And tlien tliese con be accessed directly or passed on to 
subprocesses. 1liis makes it kxik as though the program weie 
initially invoked with those rcdircx-lions from the command line. 

It's probably mote interesting to connect these to pipes. For 
example: 

^pager = $ENV(PAGER) [| “(less || more)"; 
open(STDOUT. “| $pager“) 

II die "can't fork a pa^er: $1”; 

Tills makes it u|)tx.‘iir as though your program were called with 
iLs stdout already pi|xxl into your pager. You can also use this kind 
of thing in conjunction with an implicit fork to yf>iirsclf You might 
d<^ this if you would rather handle the ix>st prcKessing in your own 
piograni, just in a different pnxess: 

head(100): 
while «>) I 
print; 

I 

sub head I 

ray $lirses = shifL 11 20; 

return if $pid = o|ten(STDOUT, "1 ; // return if parent 

die "cannot fork: Jr unless defined $pld: 
while C<STDIN» I 

last if ^$lines < 0; 
print; 

I 

exii; 
t 

lliis technique t^tn be applied to repeatedly push as many 
niters on your oui[)ul sircitm as you wLsh, 

4, anii-K I/O Issues 

Tlxise topics aren't railly urgiimenLs t^lated to open or sysopen, 
but they do ^ifTecl wliai you do with your open files. 

4*1 Opening Nun-File Files 

When is a llle not a file? Well, you could say when it exisLs 
hut Isn’t a plain file. We'll check whether it's a symliolic: link first, 
ju.sf in case, 

[f ( 1 $fi]e II 1 -f _) t 

prim "$file is not a plain file\n": 


What Other kinds of files are there than, well, files? Directories, 
symlx)lic links, named pipes, Unix-doniain stxrkets, and lilcxk and 
chamaer devices. Those are all files, too-just not plain files, 'lliis 
isn't the same issue as iieing a text file. Not all text files are plain 
files. Not all plain files are text files, Ihafs why there are .seiximte 
-f and A' file tests. 
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To open a direaDry, you should use tlie opendir funcLi<jn, 
then pr(x:c.s.s it with readdir, careHilly restorin|> the dtrecEoiy 
nanie if necessary; 

opendir(DIR* Sdirname) or die "can't opendir Sdirname: $!": 
while (defined($flie readdir(DlR))} I 

# do eomerhlng with *$dlrtianie/$f.1]e'' 

I 

elOfiedlrCDTR); 

If you want to |>rtx.css dkettories nL*euESively, it’s better to ase 
ilie File:: Find nxKliiIe. l^'or example, tliis prints out all files lecursivdy 
and adds a slash to their names if the tile Ls a diiectoiy. 

tARG? “ qw( J tinlesi? MRGV; 
use File;:Find: 

find sub t print $Fi1e: iFind: d 'i\ "Vn" I, @ARCV: 

'Itiis finds all [x)gas syinlx)lic links Ixaieath a txirlicnlar 
dintxtory: 

find sub 1 print "$Flln: sFInd: jnampXn" If I le ), $dlr: 

As yon sec, wiifi symlxilic links, yon am just pretend ilxii it is 
what it points to. Or, if you want to know what it points to, then 
leatilink ts emailed for: 

if (-] $fnn) ( 

if CdeFlnedtSwhither ” reedHnk($fiXe))j t 
print polntB to Swhlther\n": 

I else [ 

print points nowhere: 

( 

I 

4,2 Opening Niimed Pipes 

Nanmi pipes are a dilTcTent matter You puiiend theyYe regitUir 
files, but their ripens will normally block until lliene is bodi a reader 
and a writer. Unix-domain stxkets are itither different liea.sts as well; 
the/te descril:)ed in Uiiix-l>oiiiain TCP ClienLs and Servers in the 
artide Perl lnterproces.s Communications (MacTedi, ()8/2()03)* 

Wficn it comes to opening devices, it can be easy and it cun lie 
tricky. Well as.sume lliai if you'ie opening up a bkx:k device, you 
know what you're doing. Tlie diameter devices are more inicTesting. 
Ttiese are typicjilly used for rntxlems, mice, and sf>me kinds of 
printers. It’s often enough to open them airehilty: 

sysopenCTTVlN. “7dev/ttySl‘\ O.RDWR | 0 HDEUV | O NOCTTY) 

# tO_NOCTTY no iotiget noeded an POSTX systenis) 
or die "can’t open /dev/ttySl: S!"*; 

opeii(TTT0I7r, "+>£.TTYir) or die "can’t dup TTYIH; $E": 

$ofb - select (mom r ^ i\ select C$ofh}; 

print moUT “+++at\015"; 

^answer « <TTYIN>: 

Willi descriptors tluU you fiavenl opencfl using systipen, such 
as sockets, you am set tliem to be nordiloddng using foitl: 

usa Fcntl: 

fcniHCoTinection, b'_SEi:¥l, 0_N0NBL0CK) 
or die "can*t set non blocking: $!": 
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Rallicr Uuin losing yoursdf in a moniss of rwis^ing, luming 
ioctls, all dissiniikir, tf ymrne going lo manipulaic ays, Ks l>esi to 
make calls out to the stty(l ) program if you liave it, or else use the 
portable I’OSIX interface. To figure this all out, you'll need to read 
ilu: iennias(3) manpage, which descTibes the POSIX interface to tty 
devices, and then the POSIX manpage, which descril')es Peii's 
interface to POSIX, There are also some high-level rntxlules tin 
CPAN that can help you with these games, Clieck out 
'renn:;ReadKey and Temi::RtradIine, 

4.3 Opening Sockets 

Whit else c'an you open? To open a cunnecticjn using,sockets, 
you won't iLse one of Perl's two open functions. See Sockets: 
Clieni/Server Communicalion in the article Perl Interprocess 
Q)ininunications (Mac lech, 08/2003) for llial Here’s an example. 
Once yoti have it, you t'an llsc FH as a iiidiiectional filehandle, 

uso TO::Socket: 

local ‘FTI “ TO::Socket:: TNET-!>iiiew(“WWW. perl,com;SO**); 

For opening tif) a URL the LWI* mcxlules from CPAN are jiLst 
what die dcKtor ordered, lliere's no filehandle inierfact:, but its still 
easy to get the contents of a ckKinnent: 

uae LWP;;Simple: 

Sdoc - ^et(*http://www*l [npro.Tio/lwp/‘J: 

4.4 Bimiry Files 

On certain Icg^icy systems with what could charitably Ik* tallcxl 
temiinally cxinvoluted tsome would .say bit)ken) I/O models, a file 
Isn't a file-ai least, not with rL‘S|x?cl to the C standard I/O libnirv'. On 
thc’se old .systems whose libraries (but ntH kernels) dLsiingtiish 
iKtween text and binary str^ims, to get files to IkIuivc (>n>|x.Tly 
you'll have to bend over IxickraRls to avoid niisiy prolilaus. On 
sui h infeliciions sysicaiLs, stK'kets and pijx^s are alracly opened in 
binary motle, and tliere ts currendy no w^ty to turn ihat olT With 
files, you liave more: options. 

Antxher erption is to llsc die binnKxle lirndion on lire 
apprtrpriale handles Ixffoie doing regular I/O on them: 

biimodetSTDlN); 

binmode(STDOUT): 

wbllo «STDtH» ( print I 

Passing sysopen a non-standard Hag option will also open 
the file in hirtary mcKle on those .systems that suppon it. This is 
the et|uivalent of oj>ening the file normally, then calling 
bimiKxle on the handle, 

sysopen(RTITDAT. “recordE.datn*'. 0_RDWR | 0_B1WARYJ 
II die “ennU open records .data: 

Now you {"an use read and print on that handle without 
worrying alxMJt die non-standard system I/O Ihnir/ bre;iking yrmr 
data. It's ncX a pretty picture, hut dien, lej^cy s-y'?^erns seldom are, 
CF/M will lx with as iiniil the end of days, and after. 

On systems witli exotic I/O sy^stems, it turns out that, 
astonisliingly enough, even unhurfered I/O using sysread and 


sywrite might do sneaky' data mutilation behind your liack, 

while (sysreadtWitHNCE. $buf. t0?4)) ( 
sy SWT its {WHITHER, length ($biir)) ? 

) 

Depending on the vicissitudes of your nmiiine system, even 
these calls may need binmode or 0_B1NARY tirsi, System.s 
known to lye free of such dilficulties include Unix, the Mac OS, 
Plan 9t and Inferno. 

4.5 File Locking 

In a multitasking environment, you rtiay nc^cd lo lx? careRtl not 
to collide witli other paxesses who want to do I/O on the same files 
as you am working on. You’ll often need shttred or exclusive loc'ks 
on flies for residing and w'riting respectively. Ytiii might just pretend 
thit only exclusivK" kxks exist. 

Never use tlie existence of a file < $file ;is a locking indication, 
IxKause tliere is a race condition between the test for dx: existence 
of the file and its aeration. It's possible fi>r antMlier puKcss to create 
a file in the slice of lime iKtwcen your existence check and your 
ailcmpl to create die file. Atomicity' is criticid, 

Perl's mexst ponable kKking interface is vfa die (ItKk function, 
whose simplicity is emulattxl on systems that don't directly support 
it such as SysV or Windows. Tlie underlying semantics may aftecT 
1 r)w it all works, so you should learn hf)w flex k is implementtxl on 
yt)ur system's nf Perl. 

File kx'king dexs not lock out antXher pixxess tkit would like 
to do I/O. A file kxk only Icxrks out others trying to get a kxk, not 
pjtKcsses uying to do I/O. Becaitst* kxks are advisory, if one 
prtx‘es.s usc^ kK king and another dtxsn!, all IxLs aie off. 

By default, tlie lltKk aiW will bkKk until a lock is gjimted. A 
rut|uest for a sliamd kxk will lie gmnttxl as s<K>n as there Ls no 
exclusive locker. A ret|ue.si for an exclusive Icxk will lx granted as 
stxin as them is no ItKkcr of any kind. Uxis are on file descTipfors, 
ntX file names. You ain't kxk a file until you open it, and you cun'L 
hold on to a kxk once* the file lias been closecl 

Here’s ht>\v lo get a bkxking sliared kxk on a file, typically 
ascxl for reading: 

use 5*004: 

use Fcntl qw(;DEFAULT :flock): 

opcn(FH, filonanie'*) or die "can't open filename; $!": 
fWk{FH. TiX:X_SH) or die "can't lock filenanie: $f": 

t now read froiti FH 

You can get a non-bkxking lock liy using 10CK_NI1 

flock(FH, L0CK_SR | L0CK_NB) 

Of die "can't lock filename: $!": 

This can Ik u.seful for pnxlucing more aser-friendly Ix^havifx 
by w'aming if you’re going to lx? likxktng: 

use 5.004; 

use Fcntl qwt:DECFAULT :flock): 

opentFH, "< filename”) or die "can't open rilcnanc: $!"; 
unless (flonk(FH, L0CK_SH | UXK^NB)) I 

S| = 1; 

flock(FH. TXtCK.SH) or die "can't lock filename: $1”: 
ptluL "got it.Vn" 

] 

now read from FH 
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To get an exckusive k)ck, typicaJfy used for wriiittg, you liave to 
fx^ careful. We syso|xn tlie file so it can l>e locked befoie it gets 
emptied. >011 can get a nonbim'king version using iOCKyX \ 
LOCK.NIi. 


5^004; 

use Fentl qw{:DEFAULT :flock)I 
sysofjEtiCFH, "fllenaae". 0 WHOKLY | 0_CftEAT) 
or dio ■‘can't open fllcnamci 
flocktFB* IjDCK_RX) 

or die “can't lock filename: $3": 
truncatetFH, 0 ) 

or die “can't truncate filename: $!”: 

# now write to PH 


Finally, due to the uncounted millions who cannot lx* 
dissuaded from wasting cycles on useless vanity devit.’es called hit 
counters, heie's how to inclement a numlxr in a file safely: 

use Fcnll qwtmEFAULT ifluuk): 


sysopen{FHp “nuraflle'*. 0_RDWR | 0._CKMT) 
nr die “can't open nimfile: $1“; 
autoflasb FH 

iofb = f:^>lect(FHh $| ” t; aelcct 
flocktFH. TJDCOXJ 

or die “can't write-lock tiumfiler St": 

$nun “ <FH> || 0: 
seektFH. 0. 0) 

or die “can't rewind nuafile t $3"; 
print FR Snutu+l, “\n" 

or dio "can't write lumiflle: $!“; 

LruncaLed'TU telKFii]) 

or die “can't truncate tiuraflle: $1"; 
closetFH) 

or die “can't close numfile: $3'': 


4,6 lO layers 

In iVrl 5.8.0 a new T/O fmmework called TerllO" was 
introduced. Tliis is a new "plumlnng" for aH tlie I/O liappening in 
Perl; for the most part everything will work just as it did, Ixit 1\t110 
also hrotight in .some new feahifes such as the ability to tliink of I/O 
as iayers”. Orx I/O layer may in addition u> jast moving the data 
also do transfcMiiiatioiis on tlte data. Such transfomiatioas may 
include cf>mpresstnn and detximpresston, encryption and 
decryption, and iranstdrming Ix^iwten various chanicler enaxlings. 

Full di.sc'US.sion alxxit tlie features of PerilO Is exit of scc>|x for 
tliis tiit(3rial, but here is how to rea>gnize the layers Ixing used: 

1. Tile tliree-<or nK;re)-aiguincni fonn of o|xm is Ixnng used 
and die second argument contains something else in addidoti to the 
usual <, >, », I and tlieir variants, lor example: 

opftn(ffly $fh* ‘'<:utf8"H Sfn): 

2. Tlie two-argument form of binm(xle is being used, ftx 
example 

hiiimodetSfli. *‘:eficpdingtutfi6)“J: 
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APPLESCRIPT 

ESSENTIALS 


by Benjamin S. Waldie 


Becoming More Efficient through 
Folder Watching 


For the past several iiiontlis, we have explored various 
aspects of AppleScriptinjr in Mac OS X, Wc have discussed 
some l>asic Finder scripting, adding repeat loops and if/then 
stalenients to our scripts, and more. ‘Ihis month, we will 
explore a topic ol’ frecpient interesi to those wlto want lo 
automate various aspects of llicir workllow - folder watching. 

Foi DFR Watching 

Folder watching is a common automation Leclinique that 
can t>e used lo tiiake virtually any workOow more efficient. 
By configiiritig AppleScripts to monitor folders for new items 
to arrive, users are able lo set up watched hilders to 
aiiiornatically process incoming items. 

Folder watching can he extremely useful in a variety of 
situations. For example, let’s .say that a user in your office 
copies files into a drop box on your comjmtcr at various times 
liirougliout the day. Whenever these files arrive, they need to 
be processed. Since you have other work to do too, you may 
not be able to monitor ihe drop box for new files on a regular 
basis. To assist with the process, you could create an 
AppleScript that monitors this drop box for you, and then 
notifies you whenever a new item is delected. Once notified, 
you could manually process ihu detected files. Or, you cxaild 
write additional AppleScript code to process the files for you, 
completely removing all aspect.^ of manual prrx'essing. 

In some ca.ses, you need to configure a large number of 
watched folders for multiple workflows, A common 
technique for dealing with ibis type of .situation is to set up 
an AppleScript .server. In oilier wairds, any dedieaied Mac 
wliosc primary purpose is to waicli these folders for new 
items, and then process the delected items. By integrating a 
dedicated folder watching macliine into a workflow, users 
arc a!>le to hand off llicir files for processing, freeing them to 
wairk on oiher less lime consuming and repetitive tasks. 

In tliis article, we will disc'u.ss some basic w^ays to create a 
folder watching script. Then, you can expand these tech!ik|ue,s 
in order lo cTcalc ruore complex automated systems. 


Idle Folder Waiciung 

One method for writing a script that will watch a folder 
is to create an AppleScript that has been saved as a slay open 
application and makes use of ApplcScripFs idle handler. A 
slay open application is a script that, when launched, will 
remain open until manually quit by the iLser, or told to <|uit 
by the script itself, or by another .script. 

on idle 

Add code here lo watch thn folder 
end idle 

Handlers are an important, yet fairly complex topic. I wail 
explain handlers in detail in a future ankle. In the meantime, 
this tech-note provides a veiy^ brief overview of a liandler. 

A handler is a grouyr of AppleScript statements that may 
lie executed with a single comniaiid. There are two types of 
handlers in AppleScript - subroutine handlers and command 
handlers. Subroutine handlers are groups of statements, 
which arc defined by ihe developer, and called throughout a 
script, or from another script. A command handler is a group 
of .statements that is triggered by an event, such as when a 
script is run, of)ened, quit, oi idle. The idle handler is 
considered to be a command handler, 

An idle liandler will always begin with an on idle line and 
end with an end idle line. Any AppleScript code in-between 
these, two lines will trigger wiienever the script becomes idle. 
In a Slay open script, by default, the idle handler will trigger 
every 30 seconds, However, you may optionally casfomize 
this delay period by adding a line to the end of the idle handler 
that returns a number of .seconds to delay before becoming 
idle again. In the code below, tlie script would wait 1 second 
betw^een execuli(jns of the idle handler. 

on Idle 

- Add code here to watch ihe folder 

return 1 - The number of seconds the ^icript should delay 
before being idle again 
end Idle 


Renjamin Waldie is president of Automated Workflows, LLC, a firm specializing in AppleScript and workllow ;iiitt>rTiation consulting. In additi<3n lo 
his role as a cuasuhanl, ffeniarnin i.s an evangelist of AppleScript, and can frequently he seen presenting at Macintosit User Groups, Scylx>ld Seininiirs, 
and Mac World. For additional inlormation alK)ui Benjamin, please visit h ttp://w w w., n iTomatec i work 11 ows .com . or email Ikmjamin at 
; L i ^pj ri ptgi i m @ mac: xx im . 
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Once you have a shell for your idle handler, ii is time U) 
he^in adding some IV)lder watching axle. The following 
example re]>resenLs a very basic folder watching script. In 
thi.s example, the script will monitor a user specified folder 
for items. Whenever items are detected in the folder, they 
will he mewed iininediatcly to the desktop, and the user will 
he notified that items were detected and moved. I he idle 
handler in this example will irigger once every second. Of 
course, this exami)le a>uld l)e expanded to have Jiuieh 
greater fu net Iona Hty. I’or example, you could write code to 
process only new images that are placed in I he folder. The 
script coukf Ik' written to open those images in iHtoioshop, 
[)erform various image manipulations, and then .save the 
images into an oiitpttt folder 

jg,tobQt thnWntchc^dFol der 

Eet theWatchedFcjlder to cioose foldtrr 

on idle 

tell application "Finder" 

set theDetectedItems to every item of theWatebedFoider 
repeat vitli aDe tec ted Item in theDetectedltem^ 
move anetoctodTTfMti re the dnnktop 
end repoiil 
end tell 

if theDetectedltetes t 1 I then 
activate 

display dialog "New items were detected and moved to 
your desktop.'' 
end i f 
t’ctutn t 
end idle 

In the example above, the (Irst line of code indicates that 
the variable theWatchedholder will be a global variable. In 
other words, once a.ssigned, this varial>le will f)e available to 
all areas of the script, at all times. The ssecond line of code 
prompts the user to choose a folder, and assigns a reference 
to the chosen folder to the global variable the Watched Folder. 
Because ttiese first two lines of code do not fall within the 
idle handler, they will only be executed when the script is 
initially launched, 

The code wiliiin the idle liaridler executes after the 
initial code has finished running. Once executed, it 
determines whether any items exist in the chosen folder If 
items are detected in ihc folder, the script moves llietn to the 
desktop, and then notifies the user that items were detected 
and moved. 

By moving items out of tlie watclied fijldcr, ilic script 
ensures that the same items are not detected and reprocessed 
during the next idle period. lf“ necessary, the script could 
instead be expanded to keep track of the items in the folder, 
and only process when new items are added. However, this 
would require quite a bit more development. Therefore, it is 
common practice to move files from a watched folder into an 
output folder once processing is complete. 

As previously mentioned, idle handlers are used in 
scripts that have been saved as stay open applications. 
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Therefore, in order to test the code alx>ve, you will need to 
save tlie script as a stay open application, 'fo save a script 
as a stay open application, save the script as an application 
and select the Slay Open checkbox in Script Editor’s save 
dialog, as shown in Figure 1. 
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_ hMe fxteniiPfT f 


Figure I. Slay Open Appifea/ion Sane Oplton 

You are now ready to te.sl your script, haunch it from 
the Finder and .select a folder. Next, try moving or copying 
items into the selected folder, and they should be moved to 
the desktop. 

Foi.dfr Actions 

Another method of creating a folder watching script is to 
make use of Mac: OS X's built-in Folder Actions su[>j)orl. 
Folder Actions offer a more robust way to configure watched 
folders, with less coding needed. 

What is a Folder Action? 

A Folder Action is a specially written AppleScript, which 
may be attached to a folder. Folder Adiems may be 
configured to trigger when specific types of action are taken 
on the folder they are attached to. Folder Actions may be 
written to trigger whenever; 

• A folder is Q[)ened 

* A folder's opened window is moved 

* A Folder’s opened window is t:losed 

• [terns are added or removed from a folder 

Information about Folder Actions, including .sample code 
for configuring each type of Folder Action can lx: found on 
Apple Computer’s web site at 

<hTtp://w'ww.apple.com/apple.script/foiderat:Lions>. 
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Creating a Folder Action 

To create a Folder Action^ much like the idle handler^ 
you add a specific handler into your script, indicating the 
type of acfiori that will trigger the script, Different types of 
Folder Action handlers exist, and the one that you will need 
to use will depend on the type of action that you want to 
trigger your AppleScript code. A list of available Folder 
Action handlers can be found in the Folder AcHons suite in 
the Standard Addiliorks scripiing addition that is installed 
with Mac OS X. 



Figure Z Folder Aakms in the Standard Additions 
Scripting Addition 


As you can see in Figure 2, there are several different 
types of Folder Action handlers that you may include in your 
scripL Sitice this article specifically talks al>out folder 
watching, we will only discuss the adding folder items to 
Folder Action handler, which is used to process items added 
u> a folder. However, i encourage you to try t>ut the other 
types of Folder Action handlers as w'elh 

'lo create a Folder Action that will process items that are 
moved or copied into an aitachecl folcltT, add the adding 
folder Items to Folder Action handler into your script. 

on adding folder itome to theWatchodFolder after receiving 
theDetectedItems 

— Add processing code here 
end adding folder items to 

In the example above, the first line of the handler exmtains 
two lalx^Ied fxiraiTieters, theWatdiedFolder and iheDeteacx.iliems. 
'Hie^se parametei^s wall pa.ss dynamically assigned values to the 
.script whenevei- the .script is triggered* The parameter 
theWatdiedFolder will contain an AiipleStTifil alias rc‘ference to the 
folder lliat the script is attached to. The parameter 

theOetectedltems will cotitain a list of AppleStripr alhis references 
to the items that were added to the attached folder. 

The on adding folder items to handier will only trigger 
when new items are added to the attached folder, providing 
to the scripl a list of only the newly added items. Therefore, 


unlike the script we created using the idle handler, we could 
choose to process the newly detected items, without moving 
them out of the watched folder. 

Since, when the script is triggered, it will already have a 
list of newly added items, there is no need to write code to 
determine which items were detected. Instead, we only need 
to add code to process the detected items. The following 
example code, just like our idle handler, will move newly 
added herns to the desku)p, and then notify the user 

on adding folder iteme to theWatchedFolder after receiving 
theDfitectedlteiDS 

tell application "Finder"* 

move thcDetectedItems to the desktop 
end tell 
activate 

display dialog "New itetns were detected and moved to 
your desktop." 
end adding folder items to 

Once you have written your Folder Action scripl, you 
need Lo save il as a compiled script. 

/O 00 _ UniiilHl _ CJ 

Slv* iM Fo^tfef Wit£h«r Script.scpt 
' ■* PD : \ i Foid^ltoi&n SCfiptt _ in 

^ .. [ 


Line £jndliT^&: Untx Ilf i _^ 

OpiKMis. O Only _ Jii«nup 
Opvn 

CHide Extension f WewF^iif') Cancel j 


Figure J, Saving a Folder Action Script 

Place the saved Folder Action scripl into the Lihrar)^ > 
Scripts > Folder Action Scripts fokler on your computer. 
Next, you need to actually attach the script to the folder you 
want to watch. 

Configuring a Folder Action 

To atiacli a Folder Action script to a folder, launch the 
Folder Actions Setup application, wdiich is located in ihe 
Applications > AppleScript folder in Mac OS X 10.3 and 
higher. Once launchecL verify that the Enable Folder Actions 
checkbox is scfeclcd. You must enable Folder Actions in 
order for them to function. 
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Figure 4. Fnahiing Folder Actions 


CWvk iht! + button uncter the hokiers with Actiom field, and 
you will 1 k^ pn)mplc\l to scIclI a folder. Make your seleclion, anti 
click the ()fK*tt button in the folder selection dialog window. You 
will then be promptetl to select a holder Aaion ^;c^ipt to attach to 
tlic speciPied folder. Seled llie desired Folder Action MTtpl, and 
click tlie Attach button. 
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Figure 6. A Configured Folder Action 

Now that configimilion Ls complete, quit the Folder Actions 
Setup application, and test your Ft>ldef Action script by ajpying 
or moving items intt> the attached folder If everything has Ix^en 
properly configurtxl, tlien your Foltler Aaion st'ript should 
pnx.ess the items placetl in llie allacherl Ibkler 
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Figure 5* Selecting a Folder Action Script 


As the l^>lder Actions Setup a]>plicatit)n interface will 
indicate, your Folder Action script is now attached to the 
folder ihal you specified. 


Please* note that it is also passible to a>nflgnre Folder Actions 
through the contextual menu in the Finder To display the 
c<mlextua! menu, conlix)! click on the desired folder in the Finder 
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Figure 7 Folder Action Contextual Menus 



Bhcomiko Mokh FmatKr muoiioH Fou^tJt Wajcuing 


In Closinc; 

Wiile tlte idle liandIcT n>eiliod of folder w'atching can lie useful 
at times, Folder Actions offer a very useful way to configure WLitched 
folders wiihoui a loi of exim t txling. I stn)ngiy urge you to Ix^gin 
exf^loriiig Folder Actions in nioR‘ detail. As you lx.'gin iLsirig them, 
you will wonder luw ycxi ever got along without thetii. 

Until next time, keep scripting! 
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QUICKTIME 

TOOLKIT 


by Tim Monroe 

Horse Feathers 


IlVTRODUCTlOlN 

In the previous article ('^I'ickle Me" in Maclech, 
June 2004), we look a look at using the Td scripting 
Innguage and the Tk graphical user interface toolkit to 
build a Quicklime application- We saw how to use the 
QuickTimeTd extension to add to a baste Td/Tk 
application the ability to open and display QuickTime 
movies. Figure 1 shows a movie displayed by our 
sample application, called TickLeez. 



#00 SampleMovie*mov ^ 


QuickTime 


Figure I: A numie uiftdou^ ciis/dayed 
by TickLcez (Macintosh) 


Evejni Blndings 

Last time, we saw how to create the menu bar and 
menus for the TickLeez application- I^ter in this article, 
well learn how to adjust the state of menu items 
according to the current edited state of the frontmost 
movie window. Right now, we need to create some Tk 
bindings for a handful of events. 

An event binding attaches a Td command to a 
specific event related to a movie window or to some 
other event, such as a keyboard event. The -accelerator 
options we specified when creating the menu items 
affect only the appearance of the menu items, lb 
enable the keyboard shortcuts, we need to cal) the bind 
command, for instance like this: 

bind *SwinName <$appData(modKey)-n> (newDocI 

Tk also allows us to c reate bindings for activate and 
deactivate events for a window and for mouse-enter 
and mouse-exit events. Our complete set of event 
l)indings is established in tlie seiupl^ in clings procedure, 
sliown in Listing L 

Listing 1 : Setting up key bindings 

sctiipBindings 

proc setupBindings {winNain 0 l ! 
global appData 

bind .$wirLName <$appData(modKsy)-n> (newDocI 
bind . $winHaiiie <$appData (modKey)-o> ( openDoc J 
hind .$w3nNam€! <$appDati3 (niodKi?y)-q> jpxitf 

If 1 [IsMovii^Window $wlnNnmG] [ I 
* window stiite-ctLingf binding 
bind .$wintJame <Actlvate> ladjustMenus 1 
bind .SwinNanie <Deactivate> ladjustMenus I 


In this article, I want to cronlinue investigating 
QuickTimeTd, In particular, well see how to configure 
our application to react to keyboard and operating 
■system events. We II also .see how to implement movie 
editing, by the end of this article, TickLeez will 
incorporate all the standard movie playback and 
editing behaviors. 


accelerator key bincling^s 

bind .$wLnN3me <$appD3ta (j^iodKcy) -w) IcloseDocI 
bind .$wInNamc <$appData(]«odKoy) s> tsaveDocl 
bind , $wlnHaiBiG <$appDatfl (modKey) S> I saveAaDot: I 


bind .SwinName <$appData(modKey)-z> 
bind . $wiiiNaJiie C$appData (modKey ) 
bind .SwinName <SappData{modKey)-c> 
bind .^wlnN.'iinG <SappDnta(modKi3y)-v> 
bind .$winNaiiic <$appD3ta (modKoy) a> 
bind . $wiriNamG <$appData(rttodKey) b> 


f nndoDoc1 
(editOoc ent \ 
[editDoc copy} 
(editDoc pastel 
I selectDoc all 1 
IselectDoc none} 


Tim McMiroe i.s n member of tlie QuickTime etigitieenng team at Apple. You can contact liini at monroe@mactech.com. Tie views expressed liere are 
not necessarily shared by his employer. 
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bind .SwlnHame <$3ppData(modKey)'Keypress-1> \ 

I puts "TO BE PROVIDED"! 


# mistedkmecitis bindings 

bind .$wiiiM£mie <Delete> |i?dlLDc3C cut ! 

bind *$vitiNaine <JCeyPtess> "handleKey ^winl'Jame %K" 

bind »3wiriNaine <Leave> ", $wlnNa[ue configure \ 


Note the Leave iMnding: it's mainly intended for 
Quick rime VU movies, w'here the cursor is not 
automaticaily changed to the normal arrow cursor 
whert it moves outside of the movie rectangle. (Other 
media types that alter the cursor, such as Flash, do nor 
have this probieni, so one could reasonably consider 
tile VR beliavior to be a i>ug.) Keep in mind that this 
workaround is not perfect: the cursor does not change 
to an arrow^ until the cursor hotspot has completely 
exited the movie window. This means that it will 
remain as the current VR cursor if moved into the 
window's title bar. Addressing that issue is left as an 
exercise for the reader. 

Movie Playback 

Once we've loaded a movie into a movie window 
(using the configiire command), QuickTimeTcl takes 
care of all the nitty-gritty details of passing user or 
system events to the movie and making sure it rea<.:ts 
a p propria Lely to those events. Mouse events on the 
movie controller bar work fine. Moreover, QuickTimeTcl 
takes care of tasking the movie often enough to ensure 
Lininterrupled playback of linear movies or smooth user 
interaction witli nonlinear movies like QuickTime VR 
movies or wired sprite movies. 

Handling Keyboard Events 

Quick rimelcl, however, does not appear to 
provide built-in support for the standard methods of 
controlling movie playback using the keyboard. With a 
linear movie, for instance, pressing the space bar 
.should toggle the current play state of the movie. And 
with a QuickTime VR movie, pressing the left arrow‘ 
key should pan the movie to the left. 

As yoiiVe probably guessed, we can support these 
behavior,s by creating die appropriate event landings, 
'fhe setupBindings function considered just above 
binds key presses to the handleKey function, like .so: 

bind . $vi nNamei <KeyPref 5 fj> "hand 1 $winNaine VaK" 

'fhe keyword is replaced with the keysym, 

which is a special Tk designator for a key on the 
keyboard. For instance, the keysym for the space bar 
is “space'’, and the keysytn for the Shift key is "Shift_L'’, 


Our implementation of handleKey, shown in 
Listing 2, first determines whether tlie specified movie 
window is a QuickTinie VR movie or not. (The 
command ispanoramic is slightly misnamed, as it also 
returns 1 for a QuickTime VR objecL movie.) For a 
QuickTime VR movie, we use the movie widget 
commands pan, tilt, and fieldofview to adjust the view 
parameters. For linear movie.s, we use the commands 
step, play, and stop to adjust the movie Lime and play 
race. We also adjust the movie's volume when we 
receive an up arrow or down arrow key. 


Listing Hapdliitg key presses 

handicKjcy 

proc bardlcKtiy (winNaine key] ( 
appData 

set movie $appData($winU3iiie .movie) 


} 


if { t$ffiovie ispanoramic]) I 

if hantlle QTVR mavfc etminjller kcry bindin|t*i 
# (and, yt:s/Lspannriimic‘‘ Ls true for <)bject movleij ux>) 
switch $koy f 

“Right" (Smovle pan texpr I$movie pan] 10]1 
"Left" [$niovie pan [expr [$movie pan] + 10] i 
“Up" (Smovie tilt [expr [gmovie tilt] + lOjI 
"Down" l$movie tilt [expr [Smovie tiitj - 10]) 
"Shift_L" ISmovie fieldofview [expr [Smovie \ 
fieldofview] ' 5]} 

■■Control_T." I Smovie fieldofview [expr [Smovie \ 
fieldofview] f 5]1 


I 

1 elise 1 

# JmrnJlc ^Luid^n.1 inuvie cunireJItT kty hindings 
switch Skey I 

"Right" {Smovie step 1] 

"Left" 1Smovie step -II 

"Op" [Smovie configure 'volume [min 2S5 \ 

(expr 64 + [Stnovio egot volLimG]]]| 
“Down" (Smovie configure volume [max 0 \ 

[expr -64 + [Smovie eget -volume]]]I 
“space" Iif { [Smovie rate] = 01 ISmovie playI 

else ISmovie stop 11 


] 


I 


Iiislallitig a Movie Controller Callback Function 

At this point, TickLeez can open and di.splay 
QuickTime movies, and it can handle ail the standard 
meams of user interaction with the movie. Before we 
move on to con.sider how to support movie editing, 1 
should mention lliat QuickTimeTcl provides a way to 
olxserve and possibly override actions associated with 
the movie; that is to say, it provides a wrapper for 
QuickTime's movie c:onLroller action fiflCT function. 
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We installed this movie controller callback function 
when we configured our movie widget, by passing a 
procedure name to the -mccommand argument: 

. $vin]Sfame .mov configure -mccoininand control lerProc \ 
-meed it: i - realbio I 

'I he specified procedure is passed the name of the 
movie widget, a string represeniing the action, and a 
possil)ly ein]>ty list of paramctCTS associated with that 
action. For linear movies, tliese actions include 
activate, customHutionClick, deactivate, key, 
goToTime, inouscDown, pl^Yi seLSelectionBegin, 
.setSelectionDiiration, and setVoIume. For QuickTime 
VR movies, these actions also include pan, tilt, 
ficldofview, and triggedloLspoL Listing 3 shows the 
basic form of a movie controller callitack function. 

Listing 3* Handling movie controller actions 

controllcrProc 

proc controllerProc (w what 1 par [Mf [ 

if I 1 [isMovieWindow [atriiig range $w 1 endj j \ i 
return 

] 

if ($what == I 

puts "got key cvenL In cofUrolltjr actimi proc" 

1 

[ 

Normally the action is processed by the movie 
controller after our callback procedure returns. To 
suppress an action, we can execute this line of code: 

return cudo 3 

Movie Editing 

Quick I imel'cl provides a number of movie widget 
commands for performing the stiindard movie etiiting 
operations (cut, copy, paste, and so h)rlh). ll also 
provides support for muhilevel undo, that is, the ability 
to undo more rlian one previous editing operation. 
None of the QuickTime-savvy ap|>lications that we've 
built hitherto supports this very nice feature, except for 
the MooVeez application we buih in an earlier article, 
where the multilevel undo is provided by the CcKoa 
application framework. (See ‘'“Hie Cocoa nuts” in 
MacTech, December 2002.) In this section, we'll see 
[row to implement editing in Tick Lee/, anti how to 
adju.si the tale and Edit menus in accaordanee with the 
edited state of the fit^ntmost movie window. 

Handling Editing Operations 

We’ve already seen how to itivoke an edit 
command when the appropriate menu item is selected. 
For instance, in the setup Men us procedure (Listing 4 in 
the previaus article), we saw^ this line of code for 
setting up the Clear menu item* 

$in add eommand -labal ”Claar" -enmmand l^ditDoc claarl 


6jo, w'hen the user selects the Clear menu item, the 
ediiDfX' procedure is called with the ’'clear” pariimeter. 
Listing 4 sliows our implerrieniaLion of die edilDoc 
prwedure. 

Listing 4: Editing a movie 

etlitDoc 

proc edit Hoc lopl I 
global appData 

set winName [topHovieWindowJ 

$appData (SviiiNanie, movie) $op 
if i$op != '"copy"} { 

set n [inr.r eppData (Swi nMame, undoLevel) ] 
sol appDa t a ($wl riT^aTne, uudoOp , $n) $op 
setWlndowOirty $wiiLNainG 1 


ad justSize SvinName 
adjustMenua 

1 

The key step liere is the line of code that sends the 
specified operation string $op to the frontmost movie 
widget as a command. The movie widget supports these 
editing conunands: tut, copy, paste, clear, add, and 
undo. Notice that we also increment the widget’s undo 
level and store the operation siring itself in the movie 
window's global data array. In a m<)ment, we’ll see iiow 
ill esc i ten IS are used U> support multilevel undo. 

The editDoc function also calls the 
selWinclowDirty function (showm in Listing 5) to mark 
the movie window as having been changed. (Note tliat 
QuickTiiiieTcl provides a built-in procedure 
haschanged that we could use instead of reading this 
stored value; however, I prefer to keep track of 
changes to ihe movie myselL) 

Listing 5 : Marking a movie window as changed 

jict Wintld wJliriy^ 

proc setwindowDirty IwinName state! I 
global appData 

set appData(3winName,dirty) Sstate 
If ] [string mateb ''tract'* $appData Eos) 1 1 I 
wm attributes .SwlnNama modiffod Sstate 

1 

] 

Notice tlial, on MaeinU>sh coiiij^uters, we also set the 
modified attribute of the movie window; on Mac OS X, 
this ha.H the effect of drawing a dot inside the window’s 
close huUon, a.s shown in Figure 2- 
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Figure 2: A modified tmane irindow 

Undoing Editing Operations 

Whenever an editing operation is performed, 
QuifkTiineTt’l adds information about the state of the 
movie just prior to ilie edit to an edit slack* '11 ie 
number of tile topmost item on the stack is called tlic 
imdx} lemd. When a tttovie is first opened, its undo 
level is 0, Sulwqttcni editing opcraiions incremeni ihe 
undo level. 

Quickl'imelcl allows us to undo one or jnore edits 
l>y execiiUng the undo c'ommand. Ihis c'ornmand 
requires one parameter, which specifies the undo level 
we want to revert to. In TickLeez, we shall always 
revert U> the previous edit, so well decrement the 


tmdo level by tme and pass that niimht*r to undo* This 
is how we implement multilevel undo* Listing 6 shows 
our definition of the undtd>oc function* 

Listing 6: Undoing an edit 

imdor>{)c 

proc undoDftc 1 I ( 
global appOata 

set wiiiMame [ topMovieWindowj 

if t $appl>ata C$winName* undoLevel) >0] t 
incr appDataC$winEsine*undoLaVRl) -1 
$appData f$winWatiie undo \ 

$appF)a L SI ($wJ nNijtnc , uiidoLevel) 

I 

if E $appData {$winNaTiie , undoLevel) —0! f 
setWindowDirty SwinName 0 
I 

ad j UfitMeniia 
l 

As you can see, if the user undoes all edits (so that 
the undo level reaches 0 once again), we call 
setWindowDirty with the parameter 0 to mark the 
window as nut dirty* 

Sclccling All or None of a Movie 

'rhe Hdit menu in TickLeez ctinta ins die Select All 
and Select None menu items. In previous articles, 
we’ve seen how' to handle llK>se items cjiiiie easily* For 
instance, we can handle tlie Select All item by setting 
the beginning of the movie selection to movie time 0 
and I he duration of the movie selection In the duration 
of the entire movie. 
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Qiiick*lnnelcl provides the select c'ommantl that we tun 
iise to set the movie .seletlion to a spc‘dfic%l range, but it does 
not pnwitk* a coimnand tliat tetums tlie dumtion of a movie 
directly* Instead, Quick'IimeTcl provides the gertime 
coiniiiand, which netiirns an array of four movie-related 
limes: Uie current lime, tlie length of die movie, the movie 
time scale, and the movie poster time* For a specific movie 
window, we can retrieve tliat array like this: 

array set timeArr |,SappDatatSwinKaine,oiovle} gel time] 

Once weVe successliilly done that, we t^in read die movie 
diinition by l<K>king at die $LinieArr<-mQvieduralion) eleineni 
in the array; and we can mad die current oiovie time iiy 
Icxiking at the $timeAn1>movietime) element, 'fhen we am 
liandJe the two selection menu items using die seleclDoc 
function, derinct-l in Listing 7* 


Listing 7 : Selecting all or none of a movie 

proc GeieerBoe (opl I 
global appData 

set wlnNamt? [topMovleWlndowI 

array set tlmeArr [$appDat 3 C$winNaiiie*movie) 
gettime] 


jicleciDfJc 


switch — $lopl f 

all < SappData ($wiTiNaiiie .movie) select \ 

0 $timpArr(-movieduration)) 
none | $appT>at a ($wi nNania.inovie) select \ 
$timeArr( irioviotime) 0} 

1 

1 


Enabling and Disabling Menu Items 

As you know\ we need to adjust some of ilic items 
in the File and Rdil menus based on the current state 
of the frontme^st movie window (if one exists). For 
instance, if a movie has been edited, we need to 
enable ihe Save menu item in the File menu so that the 
user can save those changes, if desired. Listing 8 shows 
our implementation of the adjustMenus function, 
which is called by many of tlie editing functions weVe 
encountered recently. We handle the Save menu item 
by looking at the dirty fiekl of the stored movie 
window data, like iliis: 

if t SappData C$winNanie * di rty) ==11 I 

$bar.fi1p f^nr ryr.onf lg,ure *'Save^ -state active I 

Here, we use Tk’s entry configure command to set the 
state of a menu item. 

We can determine whether other menu items should 
f)c enabled or disaliled by executing the controllerinfu 
command. Like the gettime command we just 
considered, controllerinfb fills an array with a set of 
entries, in this case with entries that indicate the current 
state of tlic movie controller 


For instance, if the $infoArr("CUtavailable) item is 1, 
then we want to enable the Cut menu item. 


Listing 8: Adjusting the menus and menu items 

aUju^iMcnus 

prac adjustMenus |J [ 
global appBata 

set winName [topMovieWindow] 
set bar .$[winNaffle1fflbar 

if ( [string equal SappData£os) '^vindovs"] } ( 
if I [string eqtml $wiiiNaii]e “"1 I ( 
return 
J 

1 


^ SL*! the ddkult sole 
$ber.file entryconfigure 
Sbar*file entryconfigure 
$bBr.file entryconfigure 
$bar,file entryconfigure 
$bar.file entryconfigure 


■"Mew" -state active 
“Open...* 'State active 
^Close"* -state disabled 
”Save" -state disabled 
■'Save As..." state disabled 


$bar,edit entryconfigure 
Sbar.edlt entryconfigure 
$bar*edit entryconfigiire 
$bar.edit entryconfigure 
$bar.edit entryconfigure 
$bar.edit entryconfigure 
$bar.edit entryconfigure 


**Undo" 'State disabled 
“Cut** -state disabled 
"Copy"* -state disabled 
*'Paste** -state disabled 
‘’Clear** -state disabled 
"Select All” state disabled 
"Select None" state disabled 


Sbar-movie entryconfigure “Hide Controller Ear" \ 
-state disabled 


if I [string equal $appData{f)s) "windows"] ] I 

$bar*help entryconfigure **Aboiir TickLees" -state active 
1 else f 

$bar.apple entryconfigure "About TickLeez" \ 

-state active 

1 


If [ IlsMovleWliidow SwinNome] \ t 

$bar*file entryconfigure "Close" state active 
Sbar.file entryconfigure "Save As**." state active 
Sbar.edlt entryconfigure "Select All" state active 
Sbar.edit entryconfigure "Select None" -state active 


If ISappData(SwinName,dirty) “ IJ I 

Sbar.file entryconfigure "Save" *state active! 


array set infoArr [$appt>at 3 ($winNaine,tB 0 vie) \ 

controlletinfo! 

if ISappDatatSwinName.undoLevel) >01 I 

$bar-edlT entryconfigure "Undo" 'state atliveI 
If l$infoArr('CUtavallable) =11 I 

$bar-edit entryconfigure "Cut" -state active! 

If ($infoArr(-copyflvailable) ** 1] [ 

Sbar.edlt entryconfigure "Copy" -state active! 

If tSinfoArr( pasLfuvaitable) “ II ( 

Sbar.edit entryconfigure "Paale" state active! 
if (SinfoArr(-clearavaiiable) “ ll ( 

Sbar-edit entryconfigure "Clear" -state active! 


if iSappDataCSwlnName♦undoLevel) >0! ( 
set op \ 

SuppData[$winName.undoOp,SeppPats(SwinName,undoLevelJ) 
Sbar.edit entryconfigure "Undo*" label \ 

"Undo [string tolltie Sop] " 




$bar-movie entryconfigure **Hide Controller Bar" \ 
-state active 


array set infoArr ISappBata(SwiniJaine.movie) controller info} 
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Fiii* Manipulation 

Our finiil tdsk l)cf<)re wrapping up TickLeez for 
delivery to end users is lo handle the document-related 
ojieruLions — that is saving an edited movie, saving a 
movie into a new i'ile, closing a movie window, and 
ultimately quitting the application itself. As we've seen 
in previous articles, we need to track the state of a 
movie and pn)mpi the user to save or discard changes 
to it when the mtjvie window* is to be closed or the 
application Is to be quit. 

Closing a Movie Window 

When the user selects tlie Close menii item in the File 
menu (or types the appropriate keyboard shortcut), 
'i’ickLeez executes the closeDoc procedure, wliich is 
defined in Listing 9. 

Listing 9: Handling the Close memi iteni 

cItJseDoc 

proc I I I 

attemptClosG [LopHovieWindow] closing 
I 

As you can see, close Doc finds the name of the 
from most movie window and passes that name as an 
argument to the artemptClose function, along with the 
action name “closing”. The attemprClose function 
needs to look at the dirty slate of the window and, if 
necessary, display a dialog box asking ilie user to save 
or discard the changes to the movie. Listing 10 s!low^s 
our definition of aiteinptClose. 


Listing 10: Prompting the user to save a changed 
movie _ 

^ueinpiQuite 

proc atteinptClose {winNaroe action | [ 
global appData 

sot cloBoWindow I 

if tSappData(SwinNaiiie.dirty) = 1) t 

get movieNanie Itile tail $appDar.a{$wffileName)] 

set answer [tJc.m&ssageBox \ 

-parent .SwinName \ 

'title “Save changes before faction” \ 

'message* "Do you wont to save the changes yoti mado \ 
to the document \Q201GSmovieNamRUi20ID \ 
before $action7" \ 

Lype yesnocancei \ 

-icon warningl 

switeb $&nsv&r i 

yes (set cToscWtnduw [saveDoc] I 
cancel |set claseWlndow 01 
no [set closeWlndow 11 
I 

[ 

if ($clDseWindDw = 1| idiapoaoDoc SwiriNamef 

return $cloaeWindow 

I 

We display ifte Save Changes dialog box by calling 
the tk_messageOox function, this time with tlie 
yesnocancel type. Figure 3 sliows the Macintosh dialog 
box, and Figure 4 shows the Windows dialog box. 
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Do you want to save the changes you made to the 
docjjcnent '‘SampleMav3e.mov‘* before doiJng? 


( Cancel ) 





Fif*ure 3' The Save Cbcfnge^ duihf^ box of TickLeez 
(Macintosh) 



Figure 4: Ihe Save Changes dialog box of TickLeez 
(Windows) 

Noiice in Listing 10 lhal iF the ust-r st^lerUs Yes, we 
rail lUc saveDoc pniceOnre (tlcl'ined later) and tlien set 
the closeWindow variable tu the value it rettirns. Wv set 
the closeWindow variable to 1 if the user selects No and 
lo 0 if ihe user selects Cancel If cioseWirKlow is I, we 
call the disposeDoc function, defined in Listing 11, 


window that is about to close. Ills easy to implemeot 
saveDoc, using the save command provided by 
QuickTinieTc'l, as shown in Ltscing 12, 


Listing 12: Saving a movie 

silvclToc 

prot saveDoc I I f 
global appData 

set wlnfJemo [topMoYieWindow] 

* \l lilt niovif tik is in our tempt irjry diiiLxiury. sden ilit uso* 
if I [string compart: \ 

length [string length ^appData(tempDir) ] \ 
$appDatfl($winNaiiie*fiieName) $appData (tempDir) ] = 01 I 
tk_meRsageBox \ 

parent .SwlnName \ 
title “Warning** \ 

■message “Cannot save this movie into tlie current \ 
folder Anp] ease choose \u201CSave As*-Au20tT) to \ 
select a different folder.** \ 

-type ok \ 

-Icon warning 
rertirn 0 


$appl)£itu ($wl nName .movie) save 

setVitidowDirty $viiriWnine 0 
ad justHenus 
return 1 


Recall that QuickTimcTcl requires a filename for 
each open movie atid that we create a temporary file 
when die user selects the New command in die File 
mcniL If the file we are saving is located in the 
designated temporary directory, we want to display the 
alert sheet shown in Figure 5 to force ihe user to save 
ihe file elsewhere. 


Listing 11: Disposing a movie window and its 
associated data 

pror c1:l^5poseDoc IwinNamel [ 
globes 1 .-ippOata 

If f ! [isHuv ieWi ndow $vinNanieJ] At»Lurnl 
destroy , 

array unset appIUUa SwInname,* 
adj ustMenus 

[ 

The key step in disposeDoc is to call the 'I'k 
function destroy, which removes the specified window 
from the screen and disptjse of any memory it occ upies. 
We also c*all ihe array unset comm:ind to remove from 
tlie apfjData associative array any elements associated 
with the movie window. 

Saving a Changed Movie 

As we've seen, 'I'ickLee:^ calls the saveDoc function 
when the user selects the Save menu item (or types the 
appropriate keyboard equivalent). In addition, the 
attcniptClose method (Listing 10) calls the saveDoc 
function if thc^ user elects to save the changes to a 


0 mbv 


Cannot ^ave this rnoYie into the curi'ent foldcf. 

Please chaos e 'Save Ai...' to select a diffenent folder. 



Figure 5-' 'The had direciorv aieri sheet 


Saving a Movie into a New File 

When the user .selects the Save As menu item in 
the File menu, we need to elicit a location for the new 
movie file and then save the movie into that file. In 
TickLeez, we’ll execute this line of code: 

Bet newPile [tk_getSaveFiieJ 
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‘ItiL" ik^gelSavcFilc funaion displays a dialog' Ijox 
like the one shown in Figure 6. li returns as its result 
the full pathname of the specified file, or an empty 
string if the user did not specify a file. 



tigure 6: l^je fUe-saving diaiog box iHspluyi^d by Tk 

If the user does specify a file, we can write the 
movie into that file by calling the QuickTimcTci 
command flatten, as shown in fasiing 13 

Listing 13; Saving a movie into a new file 

savtMtXk* 

proc saveAsDoc 11 [ 

global appDnra 

r,ef whtNaitiii [topMovleWindov] 

act newFlie [tk_getSaveFI1e] 
it ISncwFiie i- ""I I 

$appData($wlnNamc,raoviG) flatten SnewFilc 
SappData{$iifinNamc.i3HJvie) configure -file $nowFllc 

wtn ritlo ,$wloNa£(»c [file tall SncwFJle] 

act appData($vinMame*dirty) 0 

set appData($witiNanie,fIlcNarae) $newFile 

set appData($wiTiNamc*uridoLeveI) 0 

setWlndoitfDirty $wlnName D 

\ 

adJuaiHorius 

J 

As yoLJ knxjvv, the standard Ix^havior of a Save As 
operation is for llie new movie to replace the existing 
iriovie in the existing movie window. Accordingly, 
saveAsDtX' calls the QuickltmeTcl cominand configure 
with the full pathname of the new movie file. Then it resets 
the winck)w^ title and several fields of the global data array 
associated with the movie. 

Quitting the Application 

When the user decides to quil Tiekl^e?., we need to 
perform the suintlartl quining-time operatit)ns (such as 
making sure tlie uslt saves or discards any unsaved 
changes to the movie windows). When the user selects the 
Quit menu item, Tt l calls its own exit function, which 
performs any Tcl-Sfxxific cleanup tasks. We can make siire 
that our ow^n cleanup tasks arc performed prior to that by 


renaming the exit function to some other name, like this; 
rGniini0 _exit 

‘then we can define our own exit function, as shown 
in Listing 14. 

Listing 14: Quitting the application 

cxil 

proc fix It U I 
f]u I tApp 


The TickLeez function tpiilApp is shown in Listing 
15. After we’ve inspected all movie window.s and made 
.sure that all changes have been saved, we remove the 
temporary directory we createtl earlier. Then we call 
_exit to let 'Icl perform its cleanup task.s. 

Listing 15; Handling the Quit menu item 

cjiiirApp 

prac qultApp i I [ 

fiZoba .1 appData 

sen cancelled 0 

while f i LtopMovleWindavl 1“ ****) && (Scancelled ““0)1 I 
set cancelled [expr t lot lectptClose [topMovleWlndow] \ 
quittlngl ] 

I 

if j$cariCGlled = 0) | 

# minwc rlic temp directory if it exists 
If I [file exists SappD.ita (ti>mpDlr} ] I f 
file delete -force $appl )0 LatterapDir) 

I 

_exit 

I 

I 

COMCLUSION 

dtiis brings us to ihe end of our investigation ofTcf'Tk 
and Quk’kIlmeTd as a delivery veliicle for QuickTime 
applicatioiLS. In just under four hundred lines of .script (not 
counting the l>lank lines and comments in Uie file 
Tic kUxrz.tcl), we've managed to construct a multi-window 
QuickTime playbick and editing ajjplication lfiat runs on 
Ix^th Macintosh and Windows computers. Ticklx^ez exhibits 
all the stamlard user-interaction ancl clcKument-related 
behaviors that we've come to expect of a Quicklime 
application, and it does so with a minimum of platform- 
spet'ifk' code, I think tliai Quk'kTime'rd pmvides a very 
nice wrapper for the underlying QuickTime APIs. Better 
still, its source ctxJe is freely available and can fx" easily 
mcKlified to add capabilities that it does not currently 
provide. Neither Td/Tk nor QuickTimeTd is perfect, but dl 
three packages are under active develof)inenl and promise 
to gel even better ils time goes by* 

Ac:KNt>Wl.FI>GF.MFNTS 

Thanks are due once again to Jim Ingham and to 
Mats Bengtsson for reviewing a draft of this article and 
for pnwitling invaluable feedback. 
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REALBASIC 

CHAT 


Wy Guyren G Howe 

An Interview with Geoff Perknan 


Talking with the CEO of REAL Software 


ABOtrr THE AirmoR,,* 

Guyren G Howe works in aTtifitial intelligence research 
after years of work as a technical writer and developer. Me is 
married with one child, is an Australian, and lives in Austin, 
Texas,Guyren has been working with RHALl:)asic for sevenil 
yc;irs. Most notably, he wrote the RRALbasic Curriculum (Project, 
an extensive coinputer .science curriculum, for REAL Software 
(availal>ic froiii the REALbasic website). 

Recently, 1 sat down with Geoff Perlman, the CEO of REAL 
Software, for a brief interview alxJUt REALl'jasic, 

[Guyren] Tell us a little t>f your personal and professional 
background. 

IGeoffl Alright, well let's stiut witli compuiers.rd come 
home from school, and Pd want to watch reruns of MASiL 1'he 
rertms of MASH came after Star Trc‘k. s<j 1 ended up liking Star 
Trek. Well, computers for me were the closesi that I ccaild get to 
Star Trek in real life, so that's wliai got me interested in 
t'ompulcTS. initially, my Dad I nought I tome a 'fexas Instruments 
fxjrralde terminal, and they had liASIC on there, sf> we could 
progntm in BASIC. Then, i got into programming Applesoft 
BASIC. And then, when the Mac came along, 1 convinced my 
brother who had a limousine business that 1 would write him a 
program to inick all his txders. It t<x>k me six months to write it, 
1 could write it today in REALbasic prol>ably in a tkiy, or 
less.After liigh school, \ went to wa>rk for AF&T for a couple of 
years. Our office was alxjui 300 ix*ople, and they would do the 
break .sc'hedules manually, which would take a manager one 
wliole day per week. Well, 1 said ttj one of them, ‘1 can write a 
program to do rhis^. So, i spent several weeks wriling this 
program, and it got to the point where they could press a button, 
and oui came the schedule.That led to all kinds nt' orher 
optxrrtunities. Ltter, i went to work ftir myself, doing ID 
consulting. I did ihal uritif 1990, went to work for 4D for -1 yean^, 
went hack ui consulting with 4D fora while, and then in late '97, 
came aemss CrossBASlCJ downloaded CrossBASIC, found ii 
realty interesting, conracted Andrew [Barry), found out that lie 
was not really w^orking on it full time. I asked if he wanted to. 
He said yes. 1 [)ut a business plan together, and off we go with 
CrossBASlC becoming REAlJ)a.sic, and you know the rest of that. 


On to S4>me questions about business today. How are your 
licenses distributed, between Mae and Windows and both, 
people who get professional^ standarcL,.? 

[After the interview, Geoff sent me a breakdown of recent 
.sales, which lie says are 80 percent commercial, 20 percent 
academic; 74 percent standard, 26 j>er cent professional; 77 
jx'rcent Macintash, 23 perccnl Windows.l 

Sti how does EUEAL Software go about deciding what new 
features to have in a release? 

iliat's a good tjucstion. Part of it is sort of our long-term 
strategic v ision for the pnxluct. 'I haPs a big pan. 

Is that very detailed, or is it just sort of a hn>ad concept? 

We siart will] .somelhing tliat's very broad, and we know that 
there are pieces that need to !x* implemented to make that vision 
happen. So, for example, witli our new databa.se engine; 
ultimately, w^‘'d like the REAIJ>asic databa.se engine to stand up 
there with just about any database engine. But right now, it’s 
fairly basic, no pun intended..,, 

A database engine is a noii-trivial thing tt> do; Tm a little 
surprised you haven’t tried to license something Instead 
for lliat. 

We looked at licensing, and we even kx)ked at acquiring a 
few engines, and tJxu just never .seemed to work out. St), 
ultimaicly, we decided, let's just write our own engine. Wc try to 
create layers of tetrhnology m that we can give Ixmefits to the 
customer in pieces. For example*, with I he dutalxise engine, the 
first thing we did was we created ihc virtual volume. It was a 
deliverable that wa.s a foundation for the database engine. 

Just as RRScript was the first step toward the new 
coinpilen 

Exactly right. RBScript was the ftrsl deliverable*Another big 
part of what drives tlie feature set is the feedback .system* We go 
into the feedback .sy.stem, we find all the feature requesLs, sort 
tliem by the numlx^r of people that have reported the feature 
request, and then we start Iot>king down tlie list, and we 
basically start asking ourselves, bang for die buck, wliat are the 
l)csi feiiiures? I mean, support for Palm is high up on that ILst, but 
weVe not reatly for that, so there’s no point in us banging our 
hc^ads against die wall trying to make dial happen. 'Ihat will 
liappen down the road. 
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Is there also any room for enghieers lo add their own 
sfirt t)f ereative concepts? 

Sure. Tlie new IDB for version 6: thar wouldn't have 
happened if I hadtt'i j)y,shed it. Tlie way ihe new IDK happened 
was that there w^ere just a k)t of variables that came togctlier iliai 
made tiie realize tfiai we were at a pc^int now' where it's fish or 
cut bail,We'd planned two large features for 5.5, If we did them, 
that was an even bigger iiivestnient in tlie current IDE. We knew' 
we wanted to pon the IDE to Linux. Tliat was going to lx* 
another big inve.stmem in the IDE, .so I knew' that if we didn't 
port the IDE to KEALbasic now, it probably was going Lo 
become prohibitively expeasive to ever do it in the future. 

Would you care to say what those two features were? 

Yes, one is version control, and the other is visual printing, 
laying out something ihai yf)u want to print visually nither than 
having to do it all in axle. 

So what has been Ihe most Interesting thing tliat lias 
happened in the last six years? 

Wlien Andrew' departed, it was an interesting ex(XTicnce to 
rebuild ihe engineering team, it also Ixcame clear to me as 1 
started down tlial n)ad that we had tf> grow up as a company. 
We didn't have enough fortiuil processes in place, .so we becarnt? 
a more mature company as a result.l1i;it was really interesting, 
because it felt like such an unknown to me. How quickly w'oiild 
we build a new team? How well were they going lo work 
together? Were we going to go through a lot of turnover in that 
process? 

What about difficulties? That sounds like that was a pretty 
major diffieultv'. 

Proliably the tiling that w-as ihc most difficult is that it's 
surprisingly difficult to create a culture in a company. 

1 was going to ask you about that. You’ve done a very 
good job [with thej user community. Did you set out w ith 
a deliberate vision of culture within the community and 
the company? 

It was all the things I wislied a software company did when 
I wasn't running a software conipany.Aiid thafs tiretly much 
worked out the way I wanted it to. 1 think part of that too is that 
it's easy to say well, tiiat cltx^sn’l scale, as you grow yoifre not 
going to be able to t>e as comiiiunicative, you're not going to lie 
able to answ'er email questions from Individual customers. Well 
if you Ixlicve thai, ihen ihafs right. 

Tell us more about the culture of tlie community' and tlie 
company. 

As weVc grown, fve felt ilmi ifs important for us to 
continue to lie really close to our users. A lot of companies have 
that closeness w'hen they're very, very young. And as tlieir 
prrxluct and their company matures, they kind of back off from 
that, lielieving that they can't do lltai any more. I don't Ixlieve 
that.Any cu.stomer, for example, who orders our product and 


ii(Hher.s to write .something in the commem field, will get a 
response from me, personally. People are .shocked. 'Fhey can't 
believe that anyone read the comment, they figured it just goes 
into a bucket somewhere. They can’t Ixdieve they got a respon.se 
to the comment. They a\ni believe they got a comment so fast, 
and they can't lielievc it's coming from the CEO, They're just 
amazed.Scoti Cook, who’s the chainnan of [lie board for Intuit, 
wa,s once CEO, President, founder and all that; I don't know if 
he still dexs this, tJUL f know that when he was CEO, he would 
spend a fe%v hours every week dt>ing tech SLipport for Quic'ken, 
Ix^cause he w'anred to stay in touch with customers, I think that 
was really small.In terms of our culture inside the company, I 
really like consensus, so if I .suggest .srsmething and the 
consensus is no, ihi.s isn't a good idea, unless I i'cel very, very 
strongly about it, fm going to let it lie. Now, if 1 feel very 
stixiagly alx)ut it, tlien I'm gt>ing lo iry lo amrimie to hammer 
on it to achieve consensus. 

Is there anylhmg you’d nominate as being the most 
satisfy^ing? 

There are rwo things that have Ixen the most satisfying, Tlie 
first is, it's really, really satisfying to provide people with 
something that’s so enabling for them. Thai allow's them to do 
.something that they felt they could never do before. We get 
comments on a daily basts, from people saying I could never 
have done this. I have a w'lujle new tarcer, I'm so prt>ud of 
myself for doing this or that.The second thing is tliai in the past, 
fve either worked for myself as an independent consultant, or 
I've w'orked for a com[)aiiy. And T .saw how the company 
operated, and I had my ideas about how it should lx changed 
to optrmte lietter. And a lot of that wa.s just my thoughts, I had 
no idea if tluKSc tilings would really work. And in tliat respect, 
HEAL Softw'are has Ixen an cxix'rimenl in my own vi.sioo for 
how a software company should am. 

Is tliere any'diing you yvish you’d done dilTercntly? 

Well, okay, so here is how' 1 feel about that whole idea of 
Uxiking back, about I wish I'd done this or tlxit: life doesn’t work 
that way. Every decision you make leads lo a new .set of 
variables, leads to a new scenario. Your life lakes a different 
path.Eor me, 1 see an ad in Mac Week magazine, a tiny little ad 
for 4D, saying they were looking for tech suppon peopie.So I 
sent them my resume, And that led lo Silicon Valley, which led 
to my life in the computer industry. Chances are, had I made u 
different decision at that moment, 1 wouldn't 1^ doing what I'm 
doing today. I wouldn't have moved to Texa.s, I wouldn’t have 
met my wife. So, would I have done aiiytiiing dHfereni? My 
attimde toward this is that if you like the way things are now, 
then you can't look back in hindsiglii anti say you wish you did 
an\^hing different.So I know' that's kind of a philosophical 
answer, but it's the way 1 reaUy feel alx)ut all kinds of things. 

Now the compiler is done,..* 

Wait wait wail, 'Ihe compiler is never 'done*. 


VoiuME 20, Issue 7 • MAdTECH 


An iNTFRMi-w wri'H Qvmv Pi:tU.MAN 


49 





Now lhat you>e implemented the same features you had 
in liie old compiler*.. 

WeVe switchetl the compitcr, yes, 

***can we expect any interesting new language features, 
perhaps something novel like Events? 

One of our reasons for miptementing the new compiler w;is 
we needed a Ix'tier way to extend the language. The r>ki tiompilcr 
was a hantJ-wrirten parser, anti lhat led to loUs of arnl)iguities in the 
language. Tlie new aniipiler is written using Bison, which cieares 
a very consistent language, and tliat was our first goal, to get tliat 
out and just get parity of the language. Now dial we've done that, 
there ane all kinds of tilings lhat we tliink aLx)ut adding. And, w'eVe 
alneady done some of diein — if you look at the release notes for 
SO a nil S.5, tliere are new language features in lliere. 

Nidhiiig really major* tiiougli. 

Tlicre are liigger fish to fry at this poini. We have 
optimizations we want to pui in, sup[K>ri for different Ixick ends, 
native linkers for Unux and Windows, tliat kind of stuff. So right 
now, you're seeing kind of smaller language features that are going 
into the procluct, only been use there are more iinjxiriant tilings diat 
weVe just cjecided must cimie llrst.For example, the way we 
liandle resources on Windows Ls limited by how we do oiir linking 
on Windows, We need a native linker for Windows, rather tlian the 
sort t)f hcxir-stfap linker we have now, in oixler to solve the 
ies(>urx:e probleuL So you’ll see more, bigger language features in 
the future than you're seeing now'. 

rd like U> go back lt> something that Td like you to expand 
on very briefly: just what is your long term vision? 

Tlie long-term vision for RHAIhasic' is for peofile to lx; able 
to iLse one language, om: IDE. one framework, and lx* able to 
create any kind of software tliey want and deliver that on any 
platform they need.Miglii now^ we tleliver (Hi Mat', Window's and 
Linux, but there are other plailbrms, PalmOS, Ptxket PC, Symliian 
OS lor cel) plumes. Right now; we deliver just desktt)p 
applications* and now console applicaticjns in S.5. Bui there are 
other formats that software conies in. At the llthAL Worklj 
conference, we si lowed off a new product code-named 
^iwtjrdfish, for building web applications. We warn our users lo Ik‘ 
able to build PDA, or handheld device applications. We want 
them 10 Ix^ able lo build pluguns fort>lher products.And this Ls for 
dia'e retisons, One is lhat it makes sense for tliere to be a single 
envimnment* language and framework, that ytxi can im for 
writing whatever kind of software you want, but we've come far 
enougli wiili cotupulers* and software that you should lx able to 
use a higherdevel language to do that,Al.so, pcijple inve.st a hi of 
time learning a language, and learning a framework, and learning 
an environment, so the more tilings tliey can do with that* the 
iTione confident they are going to lie that theyVe made the right 
choice in learning that environment, w hich is only going to help 
the LLser cotnmtmiiy gnow.Lasily, all those ways to deliver software 
lhat we give our customers are potential entry points for people 
that aren't using our prcxliict now. For example, if you have tut 


interest in building desktop applications, we can\ get you as a 
cusiomer tockiy. But, when we ship Swordfish, if you’re interested 
in building web appfic'aiion.s, that may lx how we get you as a 
customer. Or maylxr you ltx>k at REALIrasic and you say, if 1 learn 
diLs, not only can I build web applirations. but ! c'iin also build 
desktop applit:alions. So you may have come to us with only one 
very narrowly dcfincxl need, but tlien your confidence in chcxising 
LIS grows Ixcause you re^tlize that that investment of your time 
and eneigy is applicable to lots of oilier areas.So tlxti's kind of 
what the vision is for tlic [jrtxJut!. 

Do you get a lot of people coming from VB? 

Oh, yes. Recently, Evaas Data did a |x>ll of like a thousand 
VB users, and round lhat 43% of them were looking for an 
alternative to VB.nel. They’re looking at Java, UieyTe kxjking at 
other things. Hopefully, if we can get tlie w'ord out more in the 
Windows comniunily, they'll lx l<K)kiog at us. 

’While we’re on the subject t>f Microsoft, 1 just wondered 
about tlie Oflice APL As I understand it, some of the add¬ 
ons you get when you get Microsoft f)ffice arc actually 
written in REALbasic, is that right? 

Yes, they ih a lot ol prouayping at Microsoft using 
REALbasic. And Microsoft Queiy for Mac OS X is w-ritten in 
REALbasic. The Welcome App that U'lls ytnt alxmt die features 
and the s^)fiw^are license and so on, that's w^ritten in REALbasic. 
They would actually like lo !x* able io write Office plug-ins in 
REALbasic, but we don't siippon that yet. 

I'haEs really surprising; it doesn’t sound at all like 
Microsoft* Who caiiic to wJiom? 

lliat all started when we shipjxd Version 1 at Macworld in 
New^ York, July 1998. We were sitting iliere in our little ten by 
ten ImxhIu fetching REAlJxisic. And thesi^ tw'o guys from 
Microsoft on the ver>" first day of ilx‘ show, c‘<)me walking into 
our IxxXh* and fm just thinking the w'orst.Tliey introduce 
themselves and tliey s;iy that they're with the Mac Business Unit 
at Microsoft, and we'd like to talk to you guys about working 
together to make your protliu i talk to our [iroduct. 

So liiey came to you. 

They aime to us, at the irade show. And I was totally 
.shtxked. I thought this is the la.st thing they were interested in. 
And later, as they were porting Office to Mac 0.S X, we talked 
ulxxit adding Office siipptm, hut it was a big j<ib, and we always 
had bigger fish to fry. So when they .startetl doing the port for 
Mac OS X, they w^Tcn'l totally confident that they were going to 
pt)n the VBA code to Mac OS X. Tlieir thinking w'as lhat maylx 
we can gel foe guys from REAL Software to pn^vide this 
fimaionality, and ihen if Lite jxirt of that \TSA ctxie doesn t go 
very well, we c'an shift over to !i.sing REALbasic.As it turned tjut, 
lhat port actually went fairly smoothly. So they went ahead and 
ported the V13A .stuff, but they really did not want to promote the 
VBA stuff. We existed, they wanted us to provide a .solution, and 
they wanted to point people to us. Jliey figured we were going 


so 
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to cio a lx!tter job in that .space than ihey were goin^ ro lie able 
to do. And liecause we re gt>iag through Uidr lil)rary directly, die 
APIs are 99% the same. You could go liuy a book at Amazon on 
VB or VBA, and cliaaces are just alKiut all that code is going to 
work in RHAl.ha.sic just as it is in ihe lx)ok, and be cross-platforrm 

You’ve mentioned hand-helds and plng-ins. Are you 
prepared to say anything about the time frame for any of 
tliat sUiff? 

Not really. IPs likely to Ix.^ the next thing that we take on 
after Swordfisli. I mean, we certainly w'am to do it sooner rather 
than laLcr We don't generally talk in iiiueli detail about what 
we’re going to do in the lliiure, because we prefer to under- 
promise and oVLT-deliver. 

What at>oi]t community features? As I say, 1 tlihik you’ve 
done a great job so far of building community around 
REALbasie, hut there are some things that it seems to me 
could be improved^ For example, although I thhik RB 
Garage does a pretty good job, it may be better if 
something like that had the imprimatur of the company. 
Are there any other sort of coimuuiiity features you’re 
working on? 

We've talked alxiur a code library in the past. Our gene ml 
feeling is that we fiieler ph\cc^ like RB Garage U) do lliat I ihiitk 
tliar places like RB Garage, if tliey suiy on track, they could become 
that.On the other hand, weVe talked about building a feature right 
in«) I he IDH ihar would ac cess a .server here at RRAL .Software, 
where people could contribute code, and we could indicate tkit we 
reviewed it, and they could type in a few ke)worcis, and have it 


hnd some ftmetion thal theyVe needed. WeVc alstj talked alxjut 
ljuikling a cliat applicaticju into tlie IDE, so that if you wanted to 
ask a question, you could go to tliis chat application and it would 
say thal theie were 40 RFAlhasic' expens cmline, and you c:ould 
type in a cjuestion, so liiat j)coj>lc in our coiiuriunily lliat want to 
help etich other clon't liave just the list in order ro do ii. Ihey would 
have a more instant interaction. 

Well, tiiauks for the interview. Is there anything that 
you’d like to say to the readei:s of Macltch? 

I guess what I w'ould say is tlial if you have any impressions 
of what you think REALbasic is, and you haven't really given it a 
ihoiough nin through, you really should ltx:>k at it. A lot of jx^ople 
who are C and C++ progmmmers hear the w'ord BASIC and they 
tliiiik it’s a toy language, tliat its biterpieted, and so on. Well, it’s 
not a toy language, it's as object-oriented and as powerful a 
language as Java. It’s mac hine ccxle compiled, and youII lie able lo 
do f}raciically anytlting you were doing in C++ a lot litster in 
ltEAli>asic, and on more platforms. But you hive to l^e willing to 
kx)k at a new language, and get fKtsi the name BASIC, and leave 
Ixjhind all of your [)rejudices or preconceived notions alxjut wliai 
you think BASIC is, and what you think REAilrasic is, l>eaiuse 
chances are, iPs not anytliing like what you expea.Ihe engineers 
here at REAL Softwam are all C++ guys. But in general, they all 
piefer to ccxie in REALlTasic now, Im'ause tliey can simply work 
taster ili;m tliey c;in in C++. And they’re all extremely ailented C++ 
programmers, so il’s not that they’re lacking in that respect. 

Tlianks, 

YotPre welcome. 







com 


sm 


Memory buitt to order * so you always get the right memory with up-to-the-minute prices! 

Toll Free: (800) 895-3493 • Outside US/Canada: 805-494-9797 • Fax: 805-494-9798 


Am iN'i'KKViEW wn ii Ghofk Pkiiuvian 


Volumf; 20, Isslif: 7 • MAc'ri’Cn 


51 















PATCH PANEL 


By John C. Welch 

Access Control Lists 


A look at one of the features in Tiger 
that's going to change how Mac 
Networks are run 


Welcomi- 

With nil ihc hype LhnL Tiger is gelling For such Tx)fL.aalT 
features like multipoint iCliat, Dashlxxird, etc, I Uioiiglit tcxlay we 
should take n lcx>k ai one new feature of llger that, while not as 
obvious as such (.jlJl-gcxxlness, will have a near - insLml and far- 
levelling elTea on all wlio use the new version OS X: Hie 
implementation of Access Qmtrol lists, aka, AClLs in 'I'iger. 

Access Con-who Huh? 

ACLs are a new way of controlling, well, ctea^^ to objeas such 
as files and Fokiei:s on a compiiten iMac users currefuiy don't have a 
iradiiionai ACL iiii[)lcincriLauon ihal shi()s with the OS, Tlie ckxsesi 
ilhng we have now, is the kigin cxjiitrols. That's a list of users who 
am log in to a Mac or Macs, imd controls wliai they^ am do on a 
given Mac. So, in a stmsc, dial's an ACL. ILs a login ACL. 

Unix Permission Basics 

However whai most people use ACLs with are file .system 
object K. Note: ACls are hy no means resiricied to the file system ^ 
They can exist at any level where yon have things ymi wish to 
control access to. Hut for this anicle, ive're going to limit our 
discussion to the file system. 

W\[h current versions of Mac OS X and Mac OS X Server, you 
have traditional diree-level Unix permissions* With any object on the 
file .system, there are three levels of access: 

• (>?vner, the user liiat owns the oliject 

• Group, the gioup that hiis explicit access to the object, Ihe 
Owner does not have to IxGn ilie Group 

• everyone else, or every user who's not die Owner, or in die 
Group, or every group who is not the Group. 


Ttiere's a fourth access herc‘: rkH. Roods the super user, it 
has full access to everything so there's no need to explicitly 
include root. The Owner is always a user, it can never be a 
group. (This is a step backwards in some ways from die older 
A[ipleSiiare [leniiissions, whicli did allow for group ownership of 
a file.) I'he Group, (obviously) must always be a group, not a 
user. Kveryone else is just that. 

With in tliLs access slruclune, dieie are diree things you am do 
to an object: 

• Raid, dial is, use die eontenls of die (itijecl in a non-modifying 
manner, i.c. viewing and printing 

• Write, which let.s you modify the oiiject and/or its contents, so 
you am erase the amtenrs of die objetl, delete die object, etc* 

• Excaiie, which is what allows you to run a program, list the 
contents of a direcloiy. 

Everything you do with a File System (FS) object in Mac OS X 
is hased on diase nine bulleLs. Ids fiiuly simple, aldiough there are 
things that w^dl cxitch you off guard. For example, if you own a fie, 
but that fie Ls in a direttory dial you don't have write access for, you 
can enise the cxintenLs of diat file, but you can't delete die file iLself. 

Sometimes simple is bad 

Now, for a long tiine, diis was all you nexAied. Access was 
simple, and could lie simply controlled* Ikil in a modem computing 
environment, these .simple permr*ssi(ins fall down. For example, you 
cun liave a situation w'ith different gniups needing difTcrent access lc> 
a single direcloiy and its Hies, The obvious .solution is to put eacli 
group’s files in a diffeient direcioTy, hut then you could have .some 
files needing to lie seen by both groups* You can pur people into 
different grou[>s, but then you have to aeate anodier group with 
more restrictive pemiissioiis. In a large cximp^iny, you can easily hit 
the Mac GS X limit of 16 groups per user in this kind of situation* 
For example: You have an aceouniing group with its t>wn 
directory on a server. 

• Tlie haid of accounting needs unnesiriited access to c'VCTy objcui 
in dial directory, and unreslrictcd contnl over die directory. 


Joliii Welcli <fwelrh@pnivar.coni> is an IT Staff Member for Kan.sas City Life Insurance, a Technical Strategi.st for Provar, (htrp://www.prr>var.a)ni/) 
and die Chiel Know-Il-AIl for TackySiiin, (Iinp:/7www.tackyslLin.eoni/. He has over flteen years of experience at making Macs work with other 
computer .systems. John specializes in figuring out ways in wliich to make die Mac do what nolxxly thinks it can, showing diat die Mac Is a superior 
administrative platform, and teaching others how to use it in interesting, if sometimes frightening ways. Me al.sti does things that don't involve 
conipLileriry on occasion, or at least dial's the rumor. 
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• 11ie acciiiintiiig iranagers need to be able to mcxlify the contenLs 
of a directory, Ixil not change permiJisions 

• Tlie IS group needs full control 

• 'ilie acroLintants need to able to m<xliry files, add files, lujt 
not delete 

• Non - accounting dejyaitincni lieads need to lx." able to raid and 
list specillc files, but not nxKiil'y theni in any way 

• Everyone else has no access at itll to tire diiectoiy- 

Now, you could make the head accountant the owner, he's 
set. LS can always Lise root (if all of them have that) or sudo to 
frypass permissions. You can set everyone to 000. So far we have 
rwx???—, because we haven't decided groups. Here’s where 
Unix permissions fail We have three groups now that we have 
to deal with: 

• Accountants 

• Accounting managers 

• Departmi^nt head.s 

We couki make the group set for accounting managers, and 
now the dirt-:c:iory is rwxrwx—, and put all three groups into a new 
gioup. Wait. We don’t want dctraitment Iseads to have wriLL-/delete. 
Okiy, put tliem into everyone. Wail, we don’t want everyone to see 
inside the directoiyc The pniblem Is, you have two groups that need 
rwx, and one tliar ncxi-ds r-x. But witliin tlie first two groups, you 
don’t want one to lx* able to delete files. Okay, set the sticky bit. but 
now, the giOLip that LXJES have to Lx able to delete can’t, Ixcause 
die sdeky bit nieaas that only die liead of accounting can delete files. 
So now' he’s doing the job of die accounting inamigers. Unix 
permissions are too simplistic to handle this, and this Is not a terribly 
complex situation. If you are talking about a very large aimpany, 
tliis scenario can get much worse. 

St>mctinies, complex Is gLXJtl 

How'cver, a decent set of ACLs can luitke lliis really simj>le. For 
our example, since we don’t know^ how Apple is implementing 
ACLs in Tiger, and even if we did, we couldn't talk ahexjt it, well 
use the ACL implementation from die OpenAFS project, 
( http://www.openafs.oig /). Al’S Is the acronym for the Andrew File 
System, an open -scxirce ciistributed file system that am run on Mac 
OS X along willi almost every other modem OS, While AFS can 
easily emulate Unix file permissions, it has a much richer native set 
of permissions: 

• r lead tlie contents of files in the directory 

• 1 list die names of files in tlie Liirectop^ 

• i insen files into die direc:toiy 

• d delete files from die directory 

• w write (or modify) files into the direciory 

• k l(x:k (or mcxlify the wriie-rTHxb hit) of files in the direacry 

• a administer or ckirige die acl of die dircx:tory 

Note how the permis.sions, while more aimplex dian standard 
Unix jxmiissioas, give you finer contRil. For exaniplc, adding a file 
to a dineaory is not die same as having wilte accovs to a diiectoiy. 


Deleting is its own jxmiissioii, as is aLlminlsteriiig die ACLs of a 
directory, lliis is not the richest model of ACLs in Lise by any meaas. 
lk>di Novell and Windows have far richer ACJ. models, but I his one 
is gtxxl as an example, and mas on many more environments dian 
Novel] or Windows do. 

So let’s mvisil our accounting tjxample, but with our new ACL 
gocxlness at oui’ disfXxsaL 

• Tile haul accountant is the owner .still, and as such, he gets: 

rlidwkii He can do anything, including mexlify the rights 

of others needing access. Cool 

• The IS grfxip gets: riidwka. C3ool, they kive tlie access they neecL 

• llie acx'ounting managt^rs get: rlidwk. They can mcKlify files as 
needed, but diey can't change anyonels penikssioas in die 
directory. GxiL 

• Tilt" accountants get: rliw. They can do their work, and add new 
files as needed, but diey Ginnot clclele files, kxk files, or diangc 
pemiissions. Cool 

• ’Ihe department haids get: rl. 'Ihey can see and view the files, 
but not iiKxlily diem or die directory. 

No one else has any riglus; the directory is a bkick Ixix to diem. 
LS has die access it needs widiout needing sudo, or rex it access. If 
we ktd very strici .security needs, (Sarii-Ox or HIPAA anyone?), we 
coLild set it up so tiiat IS could manrige ACLs for a directory tlill of 
files diey could see, iiut not read. You c’oukJ even set it up so they 
aiukl mn a directory they couldn’t read at all (Yes, obviously if they 
am mamige ACLs, there's a fa,st bypas-s of ACL limitations, but the 
pom is, you have more flexibility with ACLs,) 

Another advantage dial ACLs give us is individual user 
penmssions outside of groups. So you can liave imiitiple users widi 
different access to a file system object. So you can easily assign new 
groLifis or new llsces penniwions wiihout having to mtxiify the usc*r 
;md gtoup oiganiziition of your network setup. You do have to lie 
more careful with ACLs than Unix permissions, fiecause if you aren’t, 
it’s really eitsy to give .somtxme, or a group a lot more access than 
you diought you were. 

We also don't know liow^ various cominands are going to lie 
changed, or wlial new ones will lx inlrcxiiKed to deal with die new 
pemiissions sUiictuies. But in die end, we’ie going to get a lot moie 
lienefit from ACLs than pain. 

CONOIMON 

This is a bit of a quickie look at ACLs, but it should give you 
an ido of the kind of piwer that ACLs give yoLi. Since ACLs are 
going to lx iinpleinented dmiughout Mac OS X, they .should also 
finally give you the .same [xmiLssions in die Finder as you have at 
the c:ommand line, unlike the airreni situation. With the way 
modem nciworldng environmenLs are Ixcoming more cximplex, 
even k-12, Mac OS X needed a more llexible penmssion.s stmeture, 
iQid A(!ls are the Iiest way to get there. 

Bibliogiaiihy and References 
hitp://web.niit.eclu/aasiverVunix/unk_chmocLhtnil 
hup://www.app le.c:om/ maaxsx/tiger/u n ix. h tml 
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Hinder, Address Book, Mail, and System Preferenees will 
have Spoifighi searching huik in. Spt)ilight will search 
all your existing docuriients. You don't need new 
versions of your apps, though you1l deHnilely want to 
add Spotlighi searching to your iipps. Spotlight supports 
all current file extensions and all metadara formats and 
it is extensible. It s powerful srufT. 

Ir is hard to really grt)k Spotlight until yorCve 
actually seen it demoed. As you might expect, Steve 
did a great job. lie sat down at a machine that had 
more than 100,000 files loaded on it. Tie opened a 
Finder window, then Lyj>ed the word pixur in the 
search field. Boom. Instantly, a list of 4B items 
appeared. So far, this is pretty similar to the way the 
Finder works now, but the results retrieved by 
Sfjotlight are far mure comprehensive because the 
search methodology is much more sophisticatecL As an 
example, Steve did a search on half dome and one of 
the items returned was a PDF document of a Yosemite 
map w'ith the w^ords half dome embedded in the map. 
I mean, think about that. Spotlighi fuuml a lexi label 
an image embedded in a PDF document. This is not 
your father’s search technology. 

In Steve’s demo search for pixar^ must of the items 
the Fin<ler rtiurned did not have pixar anywliere in 
tlic title. Instead, Spotlight picked up the term in 
places like a file's co]>yrighr notice. Since the files arc 
reverse indexed, you can search a large domain 
instantly. When Sieve changed pixurio pixar 2002 ilte 
results appeared as soon as he hit the last 2. 

'The interface implementation is elegant. To refine 
a search, click t>n a + button and a series of popup 
menus appear that let you refine your search. For 
example, you could .select Kind from a popup, then a 
second popup appears si> you can select for a canned 
list of file kinds (like Movies, for example). 

Once you have the search jtisi tlie way you like it, 
you can click the Save bLiiton and a smart folder is 
created in the Finder windows sidebar. This is an 
impoitant feature. Suppose you were preparing a 
comprehensive report on the mating habits of the 17- 
year cicada and you were constantly accumulating 
cicada imageiy from around the world. You could do a 
search for cicada images where color space is CMYK, 
then save the search to the sidebar. Anytime yt)U 
wanted to review your current collection, just press the 
saved search in the sidebar and the images appear 
instantly. You get the idea. Steve also showed off smart 
maillioxcs in Mail and smart groups in Address Book, 


as well as a Spotlight in System Preferences and a 
Spotlight menu icon in the right corner of ihe menu 
bar. Kight on! 

H.264 

Vhe H.264 AVC (Advanced Video Codec) has fjcen 
ratified to be included in the next generation hbdef 
DVD format and Apple has adopted it for Tiger 
QuickTime. One of the most important features of 
H.264 is its sr:alalnliLy, It scales from HD DVD down to 
3Ci cell phones. This is one of those technologies that 
really needs to be experienced firsthand to truly 
appreciate it. l^ui ilie tjuality truly is amazing. 

Safari RSS 

The big adclition to Safari is ihe integration of RSS 
(Really Simj>le Syndicali^)n) rigltt in tlie browser. Tiger 
Safari will support RSS and Atom protocols and wall 
automatically detect RSS feecLs. Safari’s new Personal 
Clipping Service allows you to automatically 
accumulate articles culled from a variety of RSS feeds 
into a single page. Safari also adris ihe ability to sk)re 
RSS queries as bookmarks. 

During this part of tlie demo, Steve stepped 
through a variety of web sites with RSS feeds, 
including Apple's .site and the New York Times. 
There's an RSS l)iitLon to die right of the address ban 
When you want to view' a site’s RSS feed, navigate to 
the site, then push the RSS button. The RSS feed 
appears as a scrolling list of ailicle links, similar to a 
Google results i>age. 

There's an RSS control panel built into ihe Safari 
RSS display page that allows you to customize the feed 
display. There's a slider Uj .set the lengtli of each anicle 
displayed in each summary, you can sort by date, title 
or article source, or select the lengih of lime lo go back 
to retrieve articles. 

Since RSS feeds tend to he behind-the-scenes, they 
can show up in some surprising places. Take in iTunes, 
for example. Yes, there i.s an iTunes RSS feed, showing 
tlie top 10 for that partieulai moment. Not sure how 
particularly useful this is, bin it is interesting! 

There's also an RSS .search Held s<j you can do a 
searcTi across all yr>Lir curreni RSS feed.s. Far more 
focused results than Google and very^ fast. More 
timely, tCK>, as RSS feet Is tend lo be updated more 
(fuit:kly than GtK>gle. 
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Corf Image and Core Video 

1'his Ls iiktr QkIc Audio for ihe im^ige processing 
iind video crowd. In a nuLshcll, image ami video 
processing is now offloaded lo the C3PU (gra[)liics 
processing Lin it), wliic h is designed for chat. This adds 
Hoating point precision and eases the toad on the main 
processor. Core Image adds in more dian a luindreti 
Ijigh-quality real time image fillers. Image Units and 
Video Units are extensiide plugins, along the lines of 
Audio Units. Developers can comhioe fiJlers and 
effects and apply them in real time, with all the work 
being done by ilie GPU. Core Video provides a bridge 
between Quickl ime and the GPU. 

Phil Sc hiller, Apple's Senior VP, gave a demo of 
both Core Image and Core Video, He brought up an 
app Chal displayed a picture of a tiger as well as a 
control panel that gave him access to some of the Core 
Image filters and effccis. The app was simple, but the 
power was very dear There are focus filters (like 
Gaussian, motion, and zoom blur), color adjustmeni 
filters, color, compositing, distortion and geometry 
filters, to name a few. There's even a set of awe.some 
Ira ns it ion filters. I'he point is, you can now easily add 
all this power to your own apps. 

These same fiiters and effects work on video as 
well, also in real time. Truly amazing. 

Dashboard 

Remember the fun of Ijuilding Control Panels? Not 
the has,sle part, hut the coolness of creating a little app 
(hut was available anywhere, no matter what app the 
user was using. Combine that concept with Expose, 
and you have the essence of Dashl:>oard, Dashl^oard 
was l)uiit with WebKit, primarily with JavaScript. Like 
Expose, it provides a layer that appears and disappears 
instantly. Instead of a set of your app's wintlow's, 
Daslibt>ard reveals a customizable set of tiny 
applications* called wldgels. Examples of w'idgets 
might be a calculator* a sticky note <organizer* a stock 
ticker, or weather tracker. 

Apple will ship a .set of widgets with Tiger, but I 
have no doubt this is going to create a brand new 
markei, much like the market for tiny control panels 
back iti the day. This one looks like a lot of fun. 

Alttomator 

Aulomaior is a visual scripting tool Sal Soghoian* 
the AppleScript Product Manager, gave a demo. 
Basically, Automat or is a visual front end for your apps 
that allows you to create a worknow based on die 
capabilities of the apy> yi>n are scripting. Sal’s demo took 


a scries (^f web sites from .Mac, sucked in all the images, 
imported the images to iPhoto, itien created a slide 
show for iDVD. He then made tfie workllow' a bit more 
generic and show-ed how he could use the same script 
across applications. This is a nice solution for folks wJio 
do not want to tackle tlie [irose of AppleStripi. 

iChat AV 

With the addition of 11.264, iGJiat AV jusi got much, 
much t'ooler. 1'he image resolution is cleaner But more 
importantly, you can now' iChai with multiple people 
at the same time. An audio iChat can contain up to ten 
people, 'fen! And a video iChal can contain four 
people. Iliat i.s awxsome, baby!!! 

Till Next Month,,, 

The only dow nside of Tiger is that it is not out yet. 
‘riiere are a lot of fun diings to play with, and 1 am 
really looking forward to the first official tleveloper 
release. I think the first thing I m going to write alioui 
is Dashboard, A great idea. 

Oh, if you haven’t done so already* be sure to head 
over to liitp;//spiderw'orks.com and sign up. By the 
time you read this, we should be pretty close to 
opening the doors! See you next month. © 
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REVIEW 


By Aaron Adams 


VNC Over SSHiThe next best thing to 
being there 


Securely control a remote Mac with two 
pieces of free software 

The al>ility to remotely control n machine can come tn 
Itandy for a variety of reasons, whether itie [>uq)ose is system 
administration, or helpin),^ a friend. Apple's most recent 
remote contrc^l offering, Remote Desktop 2.0, can be overkill 
when it comes to a simple one-to-one connect km between 
machines. Most users won't need all die features included in 
Kcinote Desktop; it\s intended for labs and other 
environments tliai require the management of large niimtx!rs 
of machines at once, not the remote control of a single 
machine. Freeware VNC, on the other hand, fits the one-to- 
one bill perrcclly. VNC stands for Virtual Network 
Computing, and it allows a u.ser to control a remote machine 
as if he were sitting at the desk in from of it, 

VNC is certainly a useful tool tor those who need 
something simpler than Remote Desktop, However, il\s the 
wild wiki web out there, and security i,s a major 
consideration, VNC was developed at a time when security 
wasn't the same priority as it is now, and the data Lransmilted 
between a VNC server and client is unencrypted. Passing 
login names and passwords, or other sensitive data, over the 
piililic' Internet in the clear isn't a good idea, and neither is 
advertising the fact that a machine can Ik eonirolled via VNC 
by leaving its corresponding TCP port open. Is there some 
way to keep VNC traffic from prying eyes? 

Yes! The solution comes in the form of another piece of 
freeware included with every Mac: Secure Shell. SSll is the 
encrypted replaccinenl for plain-text telnet, a command line 
utility used frequently on the old text-based Iniernei, with a 
few added features thrown in for g(Jod measure, including 
the ability to encrypt traffic generated by other protocols. 
This process is called tunneling because the data travels 
inside an encrypted virtual pathway crealed by the 
communicating SSH pieces. To force VNC to use the tunnel, 
it has to be instructed to connect to the local machine at a 
certain port. SSI I intercepts the traffic from the VNC client at 
that port, encrypts it, sends ii to the SSH server at the other 


end of the connection, where it is decrypted and passed to 
the VNC .server. Besides encryption, one taher advantage of 
using SSH to tunnel other protocols is ilial a server only 
needs to expose a single port for SSH instead of an individual 
port for each service (dfered, such as adclitiona! pons for 
each possible VNC session. This prevents port scanners, and 
other miscreants, from discovering VNC on a target machine. 

Making this encryption happen requires use of the ’gasp!* 
command line! Most Mae users cringe at the thought of using 
the command line liecause it's so mn-Mac-like^ but it\s a 
powerful texil that's not very hard to learn, and quickly 
Incomes an excellent exercise in abstract thinking. Don't shy 
away from encryjKing VNC sessions because of Terminal fright. 

On the remote machine*,. 

Two tilings are required on the remote machine to prepare 
if lo accept an encrypted VNC session: An SSH server and a VNC 
server, iinahling SSH on any Mat‘ is as simple as going in to 
StiJOTEg np£(|it:ptvxt'ti, l>ringing the 2t|(tpivY pane, and checking 
the h)X next to PEgotr Aoyiv. Make sure the connecting user lias 
a username and password avaitahic on the remote lx>x. 

As for VNC, a great server is OSXvnc, available at popular 
download sites, such as Version Tracker or MaclI(xlaLe. OSXvnc 
is a straightfoiward application, and riio-si of the options it 
presents are obvious and don't require an explanation. Ihe two 
itnportant things to jx^int out are dial, under the TtvEpaX tal), die 
jKirt should l>e set to 5900 for the purposes of diis tutorial, and 
that, under the Sriapivy tab, the Ovkip aXXoto 
)(owr%Tum5 (XXH) box should Ik checked. Checking this box is 
important f>ec4iuse it requires that the VNC session l)e encrypted 
vui SS! 1 and won't allow any unencrypted sessions to be 
established. It won't even let the VNC server advertise the usual 
VNC port. VNC remains totally hidden to the outside world. 

OSXvnc has the option to rec]uire a password before the 
VNC session can be csiai dished. Providing a password is 
strongly recommended. A Startup item can also be configured 
lluU starts the server with the niat:hinc, and it mcludes a 
keepalive script that restarts the server should it close for 
some reason. 


Aaron Adams Ls a LAN aclmini.sinitor, a .self-cnijikjyed Macintosh amsuitant in Dayton, Oliio, and a fexmer star of Apple's "Switch" ad campaign. He 
can readied via e-mail at adanisa@macxom. 
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On tti€ local machine.^. 

L(K:ally, a VNC client Is needed to connect to the remote 
niacliine. VNC clients are a matter of personal fjreference, and 
again, popular download sites suclj as Versionlracker and 
Mac Update have a selection. 

And now for die part everyone has l>een dreading,., die 
*gaspf* command line part! The following command serves to 
establish the tunnel Ixrtween machines. Perhaps the I'Kfst way to 
explain the coiniiiand is to write it out ami then dissect it piece 
by jdece. 

The following line needs to be entered in the lerminal; 
s.sli -NfL 3900:127.0,0.1;S900 u.ser@remote, host 
.ssh - ’the a)mmand dial sums tlte SSI 1 client to aeaie the ninnti 
• Start SSll with thei^e fiptions: 

N Do not present the user witJi a command protnpi on the 
remote machine after login is complete, 
f After the user ainhemicaics, [lut the SSll process, and hence 
the tunnel, into the background to Free up the local 
command prompt for other uses. 

L [‘orward a local pt>ft to a remote address, creating the itinnef 

3900: - Tiie port on the local machine where SSH will listen for 
traffic, Ihis port can anything >1025^ ljut lor this example 
5900 has been cho.sen Ijc^ause it is the port typically ased For 
VNC irafiic. 


127.0.0.1 - Tlie address of the miu'htne that is the uldniate 
destination For the ainneiiion. Tliis particular IP is a 
Icxipback address l)ecause in this case, the VNC client will be 
connecting to the same machine the SSH sei'ver is running 
on. Due to an SSH oddity, Iticalhost is not valid here, you 
must use the kxjpliack IP. 

:5900 - Tlie w^here the VNC server is listening on the remote 
machine. Again, 5900 is typically the jxm VNC uses. 

user “ Tlie username allowed SSH access on the remote 
machine, 

@ “at”. 

remote.hast - 'Itie hostname or IP address of the remote 
machine aifining the SSH .server 

Pill in the variable.s warli the correct values to establish an SSH 
tunnel For VNC. Alter pressing enter, a prompt rec[iiesling a 
jiaSsSWord will apjxrar. 'rhis is the SSH password For the user die 
remote macliine. 

On the kx-al machine, start tlie VNC dient. Whem it asks For a 
server, enterkxalltost. (Pmvious iastaictioassaid localixrst o>uld not 
Ix^ used at die commiinLl line ixiaiase of an SSH weirdness, but ft 
am lx used with the VNC client. Just know that Icxiilhost Is the 
Slime thing as 127.0.0J, Tliey are Ixith a desigaitf>r For the lixal 
madiine,) Wlieie it asks ftir a port, enter 59^)0, nr if it asks for a 
display, enter display (I Click tlie ainnect button, and enter the 
password For the VNC server. Congmtulatioas, iPs a tiinnt*!! 
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REALBASIC BEST 
PRACTICES 


By Guyren G Howe 

The REALbasic-Office secret decoder ring 


How to control Microsoft Office from 
REALhasic 

List limtr, \ disaissecl some ways of "breaking out" of 
RliALbasic, to call on external applitTilirins to supplement what 
yotir KEALbasic application can do, 1 lamented lhai) was unable 
to explore tronirolling Micrasofi Office from Rli, Ijccause 
aithoLigh it can do lhai really well, the dcxTiimentation for this 
feature was both inadequate and horrilily, egregiously wrong. 

Since that time, things have gotten slightly l>etter. There is 
now a wcl> page (litip:// www.reaIsoftw'a re.coiTL/office2(X)4mac/) 
from which you can download a small niinilx^r of actual, correct, 
working examples. But, there is still no docuineniation to speak 
of, and what there is, it would lead you to Ixdieve that using 
Office from REALhasic is harder tlian it really is. 

So in this article, 1 will present the apparenily entirely 
undfKTimented, super-secret really easy way to control Office 
from RB, 

Birr 

Since t c^an’t One! anywhere else to put it, a quick aside: 
there were some eirors in my ank le on RHM World, I had said 
I thought there were fifty attendees, but it turns <jul tliere were 
over a luindrecL 1 also mistakenly wrote that there were three 
seminars jxr day, hut wluii 1 meant to say was that there were 
three or four sessions at a time, and a bun< h of sessions each 
day. It was quite a gcKxl seminar prograitT 

Ta-Da! The Big Sec:ret 

Microsoft Office, on both Macintosh and Windows, 
incorf morales a fairly sophisticated built-iji scripting language 
called Visual Basic for Applications (VBA). 'Ibe really super 
secret of cantrolling Microsoft Office from REALhasic: — the one 
[ liad to offer up my first-born and a handful of magic Ixans for 
— is that REAL[)asic undcTstancfs the entire VBA namespace. 
Tills means that essentially every term you can see in Worefs 
objed inspector (more on that in a moment) can lx used in 
REALhasic. Classes from Wbrd can Ix^ used in REALliasic just by 
sticking the letters Word in front of them (and similarly for Excel 


and PowerPoint), and method and function calls on tliose classes 
can (witli one type of exception) lie used ttnmodified. So, for 
example, you can fetch the text of the front most Wbrd docitment 
with the following ctxJe: 

feiTh^f roll t Doc uiient t) 

A fujiction that cetams the te^ct of the front raoat Word 
document 

Sub G et The Front Doc tmontO As; String 

dim w Ar. Hew VordApplicat.toll 

dim doc Afi VordDuckiiiiLMU ■* w.ActiveDocuffietit() 

Return doc,Content(}*Text 
End Sub 

So the Word DrKumenl class Ixcomes the WordDocument 
tlitss in REALhasic. Alst>, the gloktl methods and properljes in 
VBA Ixcome metliod calls and properties on Word Application, 
ExcelApplication, or PowerPoint Application in REALhasic. 

'Hiere. Ibe secret's out. Not much to it, really. Now V\\ just 
fill in a few details, and explore some code examples. 

Named Arglimeni^ 

The (inly major difference between VBA and REALliasic is 
that VBA suppon.s a nice feature called named uiguments. Tltls 
means that rather than having to rememlx.T, and write an ordered 
list of bare values for the arguments to a method eall, you can 
provide them as assignment statements, like the last line of titis 
ctxle snippet (taken from the REA [Basic builpin help for the 
Office class): 

Example of Replace in VBA 

Example Visual Basic tor Appliotions ccxle to perform a 
find and replace 

Selection.Find.ClenrFotmartlnB 
Selection. Find. Replacement. Cl ea rFot oia L Ling 
With Selection,Find 
.Text " this* 

. Rep 1 aceneiiL, Text = “replace with* 

.Wrap = wdFindContinue 
.Format ” false 
.HatebCase - false 
.MatchWholeUord = false 
.MatcbWildcards = falno 
.MatchSoundsIike fal(5e 
. Mat cMll Word Forma ^ false 


Guyren G Howe works in artificial intelligence research, after years of work as a tet linical write.r and developer. He is married with one child, i.s an 
Austniliim, and lives in Austin, Texas. Guyren has Ix^ working witii REAUiask for several years. Mast notably, he wrote the RFAIbask: CuTriailum 
Project, an exteasivc computer science CLirriculum, for REAL Software (available from the REAl.lxisic w^elwiiie). You can contact Mr. Howe at 
real hasic@niaciecl i .com 
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End With 

S elec tlon .Find. Exe ctit e Rep lace: =vd Re p lac eAl 1 

This Ls great, hut the ininslatttm into RKAlixisic, given in 
the built'in documentation, doesti't work. Here’s how to 
actiially do it: 

The previous example, in KFAlbasic 
Using tlie secret decoder ring, we translate the last example 
into REAlhasic 

Dim word as New WordApplication 

Dim find As WordFind = word.ActiveDocuinient.Content.Find 

find . ClearForinatting 

find .RoplacotnonL .ClearForiBaLLing 

find.text = *»find thls^ 

find,Replacement.Text "replace with" 

find.Wrap = Office.wdEindContinue 

find.Format = False 

find.MatchCase ~ false 

find.MatchWholeWord = false 

n nd .Mat:chW[Ideards ^ false 

rind .HaLchSouindsLike = false 

find. Mat chAllWordi-'orms = false 

// Now the fun stuff 

Dim repiacefaram as New OLEParameter 

replaccParam.Valnc = Officc.wdRcplaccAl1 

// accoidirtg to Lhe docs on Find.Execute the Replace parameter 
is the 11th 

repiaceParam. Position "^11 
find.Execute replacePacam 

If you had nioi e tlian one named parameter, you wouid use 
multiple OLkParameter ol^jeas, one for each named parameter, 
and you jusi pass ilumi all, in any order, to I he method calf 

A Lasger Example 

I’m now going to go through a small, entirely anirtcial piece 
of Cfxle, intended to cram Logetlier a variety oi' tccliniques. This 
article Ls not remotely laige enough to attempt even a quick 
survey of Office’s impressive programming features, hiit I hope 
Tve presented you with just cnougli to gel y<ju up, and going on 
your own, 

'iTie code will searcli tiiixxigh all the comments in tlie front 
most Wr)rd document. It will find all the comments Liiat start with 
the word lest followed by two numbers (all separated by 
spaces). Any sttch comment will lie replaced liy a table with the 
number of rows and columns given by the two numbers, and 
then the words “Hello, World” will lx* placed into tlie cell in llie 
upper, left corner of the table. I’ll go through not only the code, 
but more importantly liow 1 worked out how to write it. Til be 
working with Word X, not Word 2001 1 don’t consider the new 
version a w^orthwhile upgrade, so what you see will probably be 
slightly different in the newer version (although the code slioukl 
still work the same). 

Note dial wMe tlie example, and my comments refer to Word, 
the same ideas apply to Excel and PowerPoint (except tliat, oddly 
enough, lk)W'erPoint doesn’t support macro ret'oixling). 

Word’s Macro Environment 

Most of whai you need to know, you can learn from within 
Word itself. In the Tools menu, you 11 find a Macro submenu, 


which provides access to Word's programming feaatres. In this 
menu, the REAJ>hasic Editor command just launches REALbasic. 
The Ret:ord New Mat'nr... commanti <ipens a dialog for you to 
name a new Macro, which is what Oi'flce caJIs a program wriiLeri 
in VBA. 


Record Macro 


Macfo name; 

MscroZ 

Assign macro to 

Toolbars Keyboard 



Store rnacro in: 

' A^l Documents (Normal) 

Oescription: 

Macro recorded 7/15/04 by Cuyrers Howe 


C Cancel "') OK 


Figtire SEQ Figure ARABiC /. 

Ihc Record Macro dialog 


AftiT you click OK in this dialog, you can execute a series 
of actions, and Word will translate those actions into a \T3A 
program to do rfie same thing again. Note tiiat yoti can’t click to 
move the insertion point while yotiVe recording a macro, 'lliere 
isn’t any way for Word to turn that action, that only makes sense 
in that document (scrolling to that point, in a window of that 
size) into a set of actions repeatal^le anywhere. 

Wliiic you’re recording the macro, Word sliows a liny little 
window with stop and pause buttons: 



Figure SEQ Figure ARABIC 2: 

Ihe Macro recording paletre 

Now, jiisr carry out the sorts of actions you want 
REALbasic to control, then hit the stop button in the little 
window. Next, go back to the Macro submenu and cluKise 
Macros.... You will then see a window showing the name of 
the macro you just recorded, along with any other macros 
you have previously written or recortled: 
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Macros 
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Figure SEQ Figure \* ARABIC 5: Ihe Object Browser 
hultori 


Alternately, you can chotjsc Object Brow.ser from the 
View menu. Any of these will show Word's Object Browser: 
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Figure SEQ Figure ARABIC J.' 7he Macros window 


Click on the name of the macro yt)y just rea)rdecL tlicn 
click Edil. Here is what 1 got when I mcorded a macro in which 
I created a table along the lines of our little project: 


ft ft _____ Normal - NcwMacros Code) ^ _ 
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EndSuO 
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jTignre 5ijQ Figure \* ARABIC 4: Ihe Word Macro editor 


There are also other windows showing at tliis pinnl, but 
describing this whole programming environment is outside 
the scope of this document, so I will stick to only what you 
need niosl for your REALbasic work. 

The Object Browser 

Recording a macro will generally give you a gotjd idea 
of the kind of commands you need to execute to do 
something. You can also examine every available comniimth 
and class in Word by opening the Object Browser. You can 
do this by clicking a button on the toolbar you see in the 
macro editing environment: 
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Figure SEQ Figure \* ARABIC 6: Ihe Word Object 
Browser 

Note the search box in the middle, at the top (results 
appear in the blank area), ITie business part for our purposes 
is below the blank area* The list of Classes is comprehensive, 
<globals>, sliown in the .screen shot, are the tnethocLs, and 
properties available in the WordApplication class in 
REALbasic. 

When you click on a class, the properties, methods, and 
constants are shown to the nglii of the class name. If you 
click on something shown there, its details are shown below, 
and it is all hyperlinked. Tilts is actually how I developed the 
code for the example. Well, that, and examining the tine 
working Word example that REAl. Stiflware has published. 

Tlicrc arc .some botiks on VBA Cl understand the O'Reilly 
book ISBN M6W2-35«-H — is quite good), and a loi of 
material online. A hit of drill-down in ihe Object Browser, 
and some expenmentalion, gave me code to do my little 
example fairly easily. 
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Tiiii Example 

To finisli up, the example. 

ReplaceC(>mmerjt.sWithTables 

An example ifiat finds a^mments in the from most Word 
document, replacing those that Ix'gin wiifi the wtsrd table 
with a table who-se dimensions depend on the rest of the 
coninienl 

Sul) Kfip 1 acoCommpn t aWi thTables () 

Dim word as Kew WordApplication 

Dim c As WordCoiinients 

c! “ word.ActiveDocunent.Cormianta 

Dim counter As Integer 
Dim eoMmsfit As WorriComiiiont 
Dim content 0 As String 
DJra width, height as Integer 
nim location As WordRange 
Lf c,Count y 0 then 
counter ^ I 
do 

cotmnent - c.Itetii(counter) 
content ^ Split(comment.Range.Text(J, * ") 
if content to} ^ "table" therj 
be,i ght = content (11. vaJ. 
widlb content (2) .vai 
location “ comment.Reference 

locfttlon.TabieS.Add(comment,Reference, width, hoight) 
location.Tables, Itemd) .Cell (1, 1) .Range.Text ^ 

"hello, world" 
else 

cotmter - counter + 1 
end 1 f 

loop until counter >" c.Count 
end if 
End Sub 

The only things that bear explaining here are that u 
Range in VBA is any point in the document, or any 
continuoas section of text in the document. A Comment 
object has several Rmige jmiperiies. The one called Range is 
the actual content of the comment, 'llie one oiled Reference 
is tile ]t>caLion of the comment in the main text. Alsu, adding 
something (in this case, a table) to a range repiaces the 
range's contents (in this case, the cominent) with that table. 
Finally, collections of things in VBA will usually have an 
IlemC) funcUon to fetcti tlie collection's contents. 

Apart from that, 1 hope you find that the mostly clear 
names for ihtngs In VBA, the ready availability of example 
code online, and the ability t<i record a macro if you want to 
know how to do soinetiiing, will make this very useful 
feature of RKALbasic surprisingly easy to use. 

Brief aside: Just before 1 finished this, REAL Software 
announced a product called Office Power Pack, based on 
this feature in REALbasic. And Microsoft themselves liave 
wriUen some of the software that ships with Office (the 
installer and the query tool) in RRAEbastc. This is a practical 
feaUire indeed, and the market for Office add-t>ns or 
applications that can work with Office has to be substantiaL 
Finally, I will note that KHALbasic's Office features are 
almost perfectly cross-platform, without modification other 
than to path strings and the like. 
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PERL BASICS 


hy Paul Ammann 

Perl Objects 


ThiN ailiclc duscril jcs thu Purl threading flavor inirodiieed in 
Perl 5.6i) called interpreter threads, or ithreacLs for short. !n tltis 
model each thread ams in its own Per! inteqircter, and any data 
sharing iK'iween threads naisi l>e explicit. 

Tliere is another older Perl tlireading flavor called the SiX)5 
iiKxlel, unsurprisingly for *5.005 versions of Perl The old mixlel 
is known to have problems, deprecated, and will probably be 
removed around release 5d0. You are .strongly encouraged lo 
migrate any existing 5.005 threads code to the new model as 
stjon as possible. 

You am sec which (or neither) threading flavor you have 
l)y running perl -V and KMiking at the Platform section. If you 
have useithreads-dafine you have ithreads, if you have 
use5005threads=define you have 5.(K)5 threads. If you have 
neither, you don't have any thread support built in. If you have 
Ixith, you are in troiii>le. 

L WimT Is A i HRPAn Anyway? 

A thread is a flow of control through a program witli a 
single execution point. 

Stumcls itn awhil ItM like a pTxxcss, dtx-sn't it? Well, it shoiiki. 
T1 treads are one of the pitxx^s of a process. Hvery pnxeis has at least 
ojte threatl and, up until now, twery prexess running Perl had only 
one tliread. With 5.8, ih[>ugli, yr>u can ox^ale extra tha^ads. We're 
going to sliow you how, w'hen, and wiiy. 

2. TilKliiVOliD Progr.\m Modpls 

There aro ihrce basic ways that you can sinalure a threaded 
[irogrtim. Wliich intxlel you chcxise depends t>n what you need 
your program to do. For tnany n<m-trivial threaded programs 
you 11 need to choose dil’ferent models for tlifferent pieces of 
your [irtigram. 

Boss/Worker 

The IxKss/worker model usually has one “lx)ss" thread and 
one or more '‘worker” threads. Itte lx>,ss thread giUJters or 
genemtes tasks that need lo Ik‘ done, then parcels tht>se tasks 
out to the appropriate worker thread. 

I’his iitodel is common in GUI and server programs, where 
a main thread waits for some event and then passes that event 
to the appropriate worker ihrcxids for prexessing. Once the event 
has Ixen passed on, the lx)ss thread goes back to wailing for 
another event, 

'llie boss thread dties rclaltvely little work. While tasks 


aren’t necessarily perfonned faster than with any other melJiod, 
il tends to have the best user-resp(>nse limes* 

Wt>rk Crew 

In the work crew mtKlel, sevenil threads are created that do 
essentially the same thing lo different pieces oi data. It closely 
mirrors classical parallel pnxessing and vector processors, where 
a large array of processors do the exact .same thing to many 
pieces of data, 

'lliis irKxlel is [>articularly useful if the system mnnmg the 
prtjgram will distribute multiple threads across different 
pnxessors. It can also lx* uscTul in my tracing or rendering 
engines, where the intlividual ilireads am pass on interim results 
lo give the user visual feedi'jack. 

Pipeline 

I’he pipeline nxxlel tlivides uj> a task into a series of steps, 
and passes the results of one step on to the ihroad prxxes.smg the 
next, luich thread d£X*s one thing {u each piece of data and 
passes the results to the next tliread in line. 

Hi is model makes the most sense if you have multiple 
tmxessors so two or more threads will he exet'uiing in parallel, 
though it can often make sense in other contexts as well. It tends 
lo keep the individual tasks small and simple, as well as allowing 
some )>ans of the pi[X"line to block (on I/O or system calls, for 
example) while orlier parts keep going. If you're running 
different parts of the (njxdiiie on dilTerent j>rncessors you may 
alst) take advantage of the etches on etch [mKrs.sor. 

This mtxlel is also liandy for a form of recursive 
programmmg where, rather than having a subroutine call itself, 
it instead creates another thread. Prime and Plbonatc i generators 
both map well to this form of the pipt-iine iiuxlel. (A version of 
a prime number generator Ls f^resented later on.) 

3- What kind of thkeads ari; Perl TfiREADS? 

If you have expcTienre with other ihraid implementations, 
you might fmd that things aren't quite what you exptxi. It's very 
im[iortant to retnember when dealing with PtrrI threads tiiat Perl 
Threads Are Not X 'threads, for all values of X, They aren’t POSIX 
threads, or DecThreads, or Java's Green threads, or Wm32 
threads. Hiere are similarities, and the broad cf>ncepls are the 
same, but if you start kxiking for implementation details you're 
going to l:>e either disjippointed or confused, Po.ssibly lx>th. 
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This is noi to sny that t^erl threatis are completely different 
from everytliing tliars ever c'oine before—^they’re not, Fed's 
threading mcKlel owes a lot to other thread models, especially 
FOSIX. Just as Perl is not C, though, Fed threads arc* not POSIX 
ilireads. So if you find yrturself looking for mutexes, or thread 
priorities, it's tinie to step back a liit and ihink al:K)in what you 
want to do and how Perl can do it. 

However it is important to rememix^r that Perl threads 
cannot rnagtcully do tilings unless your openiting systems 
threjids nllow'S it. So if your sysCeni blocks the entire prtKress on 
slee[3()^ Peri usually will as well. 

Perl Threads Arc Differeni. 

4. ThRFAD-SaFE MODltIJ!S 

Ihe addition of threads ha.s changed Perl’s internals 
substantially. Ihere are iniplicatitms for pctjple who write 
modules with XS code or external libraries. Htswever, since Ped 
data is not shared among threads by default, Ped modules stand 
a higli chance of being thread-safe or can he made thread-safe 
easily. Modules that are not tagged as thread-safe should Ixf 
tested or code reviewed before being u.sed in production code. 

Not all modules dial you might use are thread-safe, and you 
should always assume a module is umsafe unless the 
documentation say.s otherwise. I'hLs includes modules that are 
distributed as part of tfie t.trrc. Threads are a new feature, and 
even some of the standard ukkI tiles aren't iliread-.safe. 

Even if a module is thread-safe, it doesn’t mean that the 
[n{)dule is optimized lo work well wilh threads. A module could 
possibly lx‘ rewritten to utilize the new features in threaded Peri 
to intrrease performance in a ihreacled enviroiuneni. 

If you’re using a mfxlule thafs not tliread-safe for some 
reasrin, you can protect yoursc^lf by using it from one, and only 
one thread at uU. If you need multiple direads to act:c,ss stich a 
nuKJule, you can use semaphores and lots of [Kugranuiimg 
discipline to control access to it. Semaphores are covered in 
Basic Semaphores. 

5- TiiRitAD Basics 

Ibe core the threads manf^age mcxlule prervides the basic 
functions you need to write threaded programs. In die following 
sections we’ll cover the basics, showing you what you need to 
do to create a threacleci f^rogram. After that, we’ll go over some 
of the features of the threads manpage tTuxJuie that make 
tlireadcd programming easier. 

Basic ITiread Support 

Thread support is a Perl compile-time option — it's 
something dial’s tiimed on or off when Perl is built at your site, 
nuher than when your programs are compiled. If your Perl 
wasn’t compiled with tliread support enabled, then any attempt 
to use direiids will fail. 

Your programs cun use the Con fig module to check 
whether threads are enabled. If your progmm can't run without 
them, you can say something like: 


SConfigluseithreadsl or die "Recompile Perl with 
threads to run this program."; 

A pos,sibly-threaded program using a possibly-threaded 
module might have ccxle like this: 

use Config: 
use Hyt1o4: 

BEGTH I 

if ($ConfigtiiEeithread5l J | 

We have threads 
require HyMod.threaded; 

HyMod threaded; 

J else I 

r e<f u i re My Ho d„t( n t h re ad ed: 

Import MyMod_ilnLhreaded: 

[ 

I 

Since code that inns IxJtli witli and withotit threads is 
usually prcjtty me.ssy, it's l^est to isolate the thrcad-spccillc code 
in its own module. In otif example above, that's what 
MyMod_fhreaded is, and it\s only im|xmed if we're running on 
a threaded Perl. 

A Note about the Examples 

Although rhread support Is ctjnsidered to fx* stable, there 
are still a numlxrr of quirks that may startle you wlien you try 
out any of the examples Ixlow, In a real situation, care should 
be Utken that all threads are linislied executing before the 
firogram exits. Thar care has not i'jeen taken in these examples 
in the interest of simplicity. Running these examples “as is” will 
prcxluce error messages, usually caused by the fact that there are 
still threads nmning when the program exits. You should not be 
alanned by tliis. Futuna versions of Perl may fix this problem. 

Creating llireads 

The threads manpage pac kage provides the tools you need 
to create new threads. Like any other module, you need to tell 
Perl that you want to use it; use threads imports all the pieces 
you need to create basic threads. 

Tlie simplest, iiiosi simighi forward way to create a thread is 
with newC); 

use rhroads; 

$thr = threads'>new(\SsubJ): 

B^ib Bubl [ 

print “In the thread\n“; 

) 

Tlie new() method takes a reference to a subroutine and 
creates a new thread, which starts executing in tlie referenced 
subroutine. Control then passes Ixjth to die subnaitine and the 
culler. 

If you need to, ytiur program can pa.ss parameters to the 
subroutine as part of tlie thread startup. Just include the list of 
parameters as pan ol’ the thread5::new call, like tliis: 
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use threads: 

$Param!i = ""foo": 

$thr “ threads->nev(\&subl» **Parani i**, “Farum ?/, $Param3): 
ithr threadS'>Tiew{\&9Ubl, tParamList) ^ 

$thr ® threads->nRwt\&BubJ, qwCParaml Parani2 Parami) ): 

sub subl I 

my ilnboundParameterB “ 
print “"In the thread\n"i 

print “got parameters >“. join(“<>“. tlnboMndParameters), 
“CVn"*: 

J 

The Iasi example illustrates another feature of threads. You 
can spawn off several threads using the same subroutine. Each 
thread executes tlie same subroutine, but in a separate thread 
w’ith a separate environment and potentially separate arguments. 

createO is a synonym for new(). 

Waidng For A Thread To Exit 

Since threads are also subroutines, iliey can return values. 
To wait for a thread to exil and extract any values it might return, 
you can use the joinO method: 

Ufip threads: 

$Lhr ^ threads->new(\iBubl)r 

^RetumData = $thi:> joint 

print “Thread returned AKeturnRata": 

Rub subl I return “Fifty-six”. “foo". 2t 1 

In tlie example above, the jinnO meihtHl returns as soon as 
the thread ends, fn addition to waiting for a thread to finish and 
gathering up any values that the thread miglit have returned, 
joinO also performs any OS cleanup necessary for ihe thread. 
That cleanup miglii be impernanu esfxxially hir long-running 
programs that spawn lots of threads. If you ilon’t want the return 
values and don't want to wait for the thread to fini.slc you should 
atll the detachO mtihexi instead, as descTilK'd next. 

Ignoring A Tln'ead 

joint) does three things: it wails for a thread to exit, ciean.s 
up after it, and returns any data the tliread may have jRroduceeb 
But what if you're not interested in the thread's return values, 
and you don't really care when ihe thread finishes? All you want 
is for the threatl to get ileancd up after when it's done. 

In this case, you use the detachO method, Ont^e a thread is 
detached, it'll run until it's fmtshed, and then Perl will dean up 
after U automatically. 

uae threads: 

Sthr = tbreads'>iiew(\&Bubl): if Spawn the thread 

$thr‘)detach: tf How we officially don't care any more 

Bub .Bubl t 
$a = 0: 
while (1) I 


pH nr “\Sa is Sa\n*: 
sleep 1; 

I 

I 

Once a thread is detached, it may not Ix’ joined, and any 
return data that it miglu liave produced (if it was done and 
waiting for a join) is lost. 

6. Tiire.\ds And Data 

Now diat we've covered the basics of threads, it’s time for 
txir next topic: data, 1’hreading introduces a couple of 
complic’ations to chita acces.s that non-threaded programs never 
need to worry alxrut. 

Sliared And Unshared Data 

The biggest difference between Per! ttbreads and the old 
5,()05 style threading, or for that matter, to most other liircaditig 
systems out there, is that by default, no data is shared. When a 
new Perl thread is created, all the data associated with the 
current thread is copied to the new thread, and is sub,secjucnlly 
private to tkit new thread! 'Iliis is similar in feel to what liappens 
when a UNIX proce.ss forks, except that in this case, the data is 
just copitxi to a different [)art of memory within the same 
t)roc'ess rather than a real fork taking place. 

To make use of threading however, one usually wants the 
threads to share at least some data between themselves. 'I'his is 
done with the threads: :shared manpage nuxlule and the : shared 
altrilntte: 

UBe threads; 

use threads::shared: 

my $foo : shared “ 1: 
my $br3f = 1: 

threads >riew(Ruh I $fod+l: Sbar^^- l)->join: 

print “$foo\n”: jfprints 2 RJnee $foo is shared 
print “$bar\n": Sprints I since Sbar is not shared 

In the case of a sliared army, all the array's elements urc‘ 
shared, and for a shared hash, all the keys and values are shared, 
rhis places restridions on w'hat may be a.ssigned to shared array 
and hash element,s: only simple values or references fo shared 
varialiles are allowed - this is so that a private varial>le can't 
Liccidentally liecoine shared. A fead assignmetit will cause the 
thread to die. For example: 

upo thrc?ads: 

use ihreads::shared: 

my $var = 1; 
my $avar : shared = 2: 
my %hash : shared: 

,,. create some threads ,.. 

$hash{a) ~ 1: 1/ all threads see exists($hash[aI) and 

ihashlai = 1 

$hash[a) ^ Svar # okay copy by-value: same affect as 
previous 

$liashtal = Ssvar# okay * copy-by value: sank? effect as 
previous 
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$hash(a) " \Ssvar if okay - a reference to a shared variable 
$hash!aJ * \$vari This will die 
delete $baBhlal S okay all threads will see 
f e}!dsta($hash[a|) 

Note Thai a shared variatilc guarantees that if two or more 
tlireuds try lo modify it at the same time, the iiitenul stale of the 
variable will not l>ecome corrupted. However, there aiv no 
guarantees beyond this, as explained in liie next section. 

Thread Pitfalls: Races 

While threads bring a new set of useful tools, they also 
bring a number of pitfalls. One pitfall is tlie race condition: 

use threads: 

use th reads!:shared; 

my $a : ahared ^ 1: 

Sthrl - threads'>new(\&subl)i 
$thr2 = threads->new[\&£ub2}: 

$thrl->join: 

SthLr2*> join; 
print 

sub sub I I ay $foo = Sa: = $foo t 

sub sub2 \ my $bar “ Sa; $a = $bar ^ 1: I 

What do you think $a will Ix^? The answer, unfortunately, is 
"it depends." Both siibtO and sub2(.) access the global variable 
$a, once to read and once to write. Depending on factors 
ranging from your thread iinplementaLion's scheduling algorithm 
to the phase of the moon, $a can be 2 or 3- 

Race conditions are cau.sed i>y uasynchronized access to 
shared d;ita. Without explicit synclmmization, there’s no way to 
be sure that nothing has happened to the shared data Ixlween 
the time you access it and the time you update it. Even this 
simple code fragment has the possil>iliiy of error: 

use threads: 
my $a : shared = 2; 
my $b : shared; 
my $c ; shared: 

my $thrl ^ threadsOcreatetsub I Sb “ $a; $a = $b + 1: 1); 
toy ithr2 * threadsOcreatetsub I $r = Sa; $a = Sc + 1; I): 
Sthrl‘>join: 

$thr2->ioin: 

*l'wo threads both access $a. Each thread can potentially be 
interrupted at any point, or be executed iti any order. At the end, 
$a could lie 3 or 4, and iKUh $b and $c could lx 2 or 3- 
Even !ta -»'= 3 or $a++ arc not guaranteed to be atomic. 
Whenever your program accesses data or re.sourees that can 
be accessed by other threads, you must take steps to coortUnaie 
access or risk data inconsistency and race conditions. Note that 
Perl will protea its internals from your race condiiions, [)ut it 
won’t prt>tcct you from you. 

7- Synchronization and control 
Peri provides a number of mechanisms to coordinate iltc 
interactions Ixtween themselves and their data, to avoid nice 
condiiions and the like. Some of tliese are designed to resemble 


die common techniques used in thread Hbntries such as 
ptharads; others are Perl-specific. Often, the standard techniques 
are clumsy and difficult to get right (such as condition waits). 
Where possible, it is usually easier to use Perlisfi techniques 
such as queues, which remove some of the hard work involved. 

Controlling access; lock() 

Tile lockO funciion takes a shared variai>le and puts a kx:k 
on it. No other thread may kxk the variable until the variable is 
unlocked by the thread holding the lock. Unlocking happens 
atitomatically when the locking thread exits the outermost block 
that contains lockO function. Using lockO is straightforward: this 
example has several threads doing some calculations in parallel, 
and occasionally updating a running total: 

use threads; 

MSB threads::shared: 

my $total : shared ^ 0; 

sub culc I 
lor (:;) I 
my $result; 

§ (... do some calculations and set $result 

r 

lock($total); # block until ve obtain the lock 
$tOtal += Sresult: 

1 # lock impllcltiy released at end of ncope 
last if $result “ 0; 



my $t:hrl “ threads’>nefw(\&calc); 

tny $thr2 = rhrnad£->new(\&oalc); 

my Stbrl " threads >newf\&calc)r 

Sthri->join; 

$thr2 >join: 

$thr3 >join; 

print “total=$toralVn'': 


ItxkO bi<Kks the thread untiJ the variable being locked Is 
available. When lockO returns, your thread c:an ix sure that no 
<ilher thread can lock that variable until tite ouiermosi bkxk 
containing llie kxk exits. 

ICs important to note that Icxks don’t prevent access to the 
variable in question, only lock attempts. This is in keeping with 
Peri’s lotigstanding tradition of courteous programming, and the 
advisory file locking that flockO gives you. 

Yt)y may lock arrays and hashes as well as scalars. Uxking 
an array, though, w'ill not block subsequent locks on array 
elements, just lock attempLs on the array itself. 

Ijocks are recursive, which means it*s okay for a thread to 
lock a variable more than once. 'Hie lock will last until the 
outermost lockO on the variable goes out of scope. For example: 

my $x : shared; 
doit(): 

sub doit [ 

( 

lcickt§xj; # wait for lock 
lock($K): # WOOF ’ we already have the lock 
[ 

lockWx); # WOOF 
E 

lock{$x): WOOP 
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l&ci£it_soMe_iEore{) ; 

I 

I 

J # "• implicit unlock here 
J 
I 

sub iockit_SQine_iiioire ( 
lock(Sx3: # NOOP 
I f nothing happens here 

Note Thai there is no unlockO function — the only way to 
unlock a variable is to allow it to go out of sc:ope. 

A lock can either be used to guard the data contained 
within the variable Ixang locked, or it can be used to guard 
.something else, like a section of code. In this latter case, the 
variable in question does not hold any useful data, and exists 
only for the purpo.se of l>eing locked. In this respect, the variable 
Ixrhaves like the mutexes and basic semaphores of tradidonal 
tiiread libraries. 

A Thread Pitfall: Deadlocks 

Locks are a handy tool to synchronize access to data, and 
using them properly is the key to safe shared data, 
linfonunatcly, kx^ks aren't without their dangers, especially 
when multiple locks are involved. Consider the following code: 

use threads: 

my $a : shared “ 4; 
my $b : shared "foo'': 
niy Sthrl “ threadfiOnewCsub \ 
lock($a): 
file.ep 20: 
locklSb): 

Ih 

my $thr2 ” threads sub t 
lock($b]: 
sleep 20: 
lotkC$a): 

J): 

Tins program will probably hang until you kill iL The only 
way it won't hang is if one of die two threads acquires both 
locks first. A guaranieed-io-hang version is more complicated, 
but tlie principle is ilie same. 

dhe first thread w ill grab a lock on $a, then, after a pause 
during wliicli the .second tliread has probably had time to do 
so[iie work, try to grab a lock on ib. Meanwiiile, Llie second 
thread grabs a lock on $b, llicn later trie.s to grab a lock on $a. 
The setond kxk attempt for Ixith threads will block, each 
waiting for the other to release its lock. 

This condition i.s called a deadltK'k, and it occurs whenever 
two or moR* threads aR trying tcj get loc'ks on a\sources that the 
otliers own. Each thread will block, waking for the other to 
release a lock on a resource. That never iiapj>ens, tliougli, since 
the thread with the resource is itself waiting for a lock to lx* 
released- 

There are a numl')er of ways lo handle tills s<jrt of problem, 
dhe best way is to always have all tlireads acquire locks in the 
exact same order. If, for example, you lock variables $a, $i>, and 
$c, always lock $a I'lefore $b, and $b before $c. It’s alst> l>est to 


hold on to locks for as short a pcritKl of time to minimize the 
risks of tlcadlock. 

The other synchronization primitives descrilx*d l^low can 
suffer from similar problems. 

Queues: Passing Data Around 

A queue is a special ihrt^ad-safe object that lets you put data 
in one end and take it out the other without having to worry 
alxjut synchroniz;ition issues, ‘fhey^re pretty siraightforward, and 
look like this: 

use threads; 
uae 'rtiread::Qucuc: 

my $bataQueue = Thread:rQueue-^new: 

$thr “ threads->ne¥(sub ( 

«hiis (SDataElement ^ $DataQueue >dequeue) t 
print “Popped SDataElemeiU off the queueAn": 

) 

11 : 

SDataQueue->enqoeuo(l2): 

$DataQu.eue-)enqiLietieC"A** * "B*, 

SDataQufiue->eiiqueue(\Sthf): 
sleep 10; 

$Data(^eue'>enqyeuetundef): 

$thr->join: 

You create the qtieue willi new 'l'hreatl::Queue. Tl ien you am 
add lists of sc'alars onto the end with cnc|ueue(), and pop sc;ilais off 
the front of ii with ilet)ueue(). A queue has no fixed size, and can 
grow as needed to hoki everything pushed on to it. 

If a queue Is empty, tlequeueO bUnks until another thread 
enqiieue.s something. This makes queues ideal for event loops 
and olher communications between tlireads. 

Semaphores: Sytichronl/tng Data Access 

Semaphores are a kind of generic locking mechanism. In 
their most l^jasic form, they fxrhave very much like lockable 
scalars, except that they canl hold data, and that they must be 
explicitly unlcxked. In tlieir advanced fbnn, they act like a kind 
of ctiunler, and can allow multiple threads to have the lock' at 
any one time. 

Basic semaphore.s 

Semaphores have two meiluxls, downO and up(): downO 
decrements tlie restjurce count, while tip increments it. Calls to 
downO will l>lDck if the semaphore's current count would 
decrement below zero. This program gives a quick 
demonstration: 

u.*;e threads; 

uso Thread;:Semaphore: 

my Ssemaphoro “ nev Thread; :5eme.phore; 
my SClobalVariable : shared = 0: 

$thr] * Jiev threads \§isanple_stib* I; 

$thr2 “ nev threads V4saniple_sub, 2; 

$thr3 = new threads \£(sampl€^sub, 1; 

sub sample_sub t 

my SSubNumber =" shift @ : 
my &TryCovuit = 10: 
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my $TtOcaJCopy; 

SlEEp Ir 

while {S'l'tyCount—) ( 

$seitiaphoE-e->down: 

$LocaXCopy "" ^GlobalVariable; 
print ""STryCount tries left for sub $SubNL|]nber 
C\$GlobalVnriablc!! in $GlobfilVariablc) \n'': 
sleep 

$],ocalCopy-H-: 

$GlobalVariable = $LooalCopy: 

$ semaphore-)^ up: 

[ 

] 

$thrl->join: 

Sthr2->jt>in: 

$thr3 >Join; 

The three invocations of the subroutine ah operate in sync. 
The sciuaphorc, Lliough, makes surt‘ that only one ihreati Ls 
accessing the glc;bal variable at once. 

Advanced Semaphores 

By default, semaphores beliavc like kxks, Icuing only <mc 
thread downO them at a time. However, there are other uses for 
semaphores, 

Bach semaphore has a counter attached u> it. By default, 
semaphores are createtl with die counter set to one, downO 
decrements the counter by one, and iip() increments by one. 
However, we can override any or all of these defaulis simply by 
passing in clLBerent valties: 

iif?c threads; 

USE Thread;;Semaphore: 

my $setiiaphore = ThreadSemaphore’>new (5): 

# Creates a semaphore with the counter set to five 

$thrl = threads->tiew(\&subl); 

$thr2 = threadf!->new(\ftfiiJbl); 

sub subl [ 

$ sema pho re > d own C b); if Dec r emeu t s the c ount e r by five 
# Do stuff here 

.$5eiiiaphore’>upt5): /f Increment the counter by five 

1 

$thrl’>detach; 

$thc2->detach; 

If downO attempts to deerrement the counter below zero, it 
blocks until the counter is large enouglc Note tliat while a 
semaphore can be created with a starting count of Eero, any upO 
or downO always changes the counter by at lea.st one, and .so 
$seinaphore->down(0) is t!ie same as $semaphore->down(l). 

The C[nes[ion, of course, is why would you do something 
like lliis? Wliy create a semaphore with a starting count that's not 
one, or why deciTeinent/incremeni it l>y more than one? TIic 
answer is resource availability. Many resources that you want to 
manage access for can be safely used by more than one thread 
at once. 

Kor example, let's take a GUI driven program. It has a 
sernaplujre that it uses to synchronize access to the display, so 
only one thread is ever drawing at once. Handy, liut of course 
you don’t want any thread to start drawing until tilings are 
properly set up. In this case, you can create a semaphore whth a 
counter set to zero, and up il when tilings are rc'ady for dniwing. 


Semaphores with counters greater than one are al.so useful 
for establishing quotas. Say, for example, tliiit you have a 
number of tlireads that can do I/O at once. You don't want all 
the tlireads reading or writing at once though^ ,sin€e that can 
potentially swamp your I/O channels, or deplete ytsur prexess' 
cjuoui of filehandles. You can use a semaphore initialized to the 
numlxT of concurrcri! I/O rccjuesis (or open files) that you want 
at any one time, and have your tlireads quietly block and 
imbltx'k theiTLselves. 

Larger increments or decrements are handy in those cases 
where a thread needs to check out or return a number of 
resources at once. 

cond_waitO and cond_signalO 

'lliese two Rinctioas c'an be u,sed in conjunaion widi locks to 
notify co-operaLing ihreads lhat a restnirce lias tetxime availaiile. 
Tliey are very siinilar in use to the funclions found in ptlire^ids. 
However for most purposes, cjiieues ate simpler to u,se Lind more 
intuitive. See the tl^^e^lds:;shaled maopage for more details. 

Giving up control 

There are times w-hen you may find it useful to have a 
thread explidlly give up the CPU to another thread. You may be 
doing something processor-intensive and want to make sure tliat 
the user-interface thread gets called frequently. Regardless, there 
are times that you might warn a thread to give up the processor. 

PeiTs threading package provides the yieldO function dial 
does this. yieldO is pretty straightforward, and works like this; 

threadiJ: 

sub loop I 

my $thread = shift: 

my Stoo =50: 

vhilet$foo"} t print ""In thread $threed\rt’* I 

threads->yield: 

$foo = 50; 

while(^foo^) t print “tn thread $tbread\n’* ] 

I 

my $threadl = threads-)neir(\SilQop. 'first"): 
my $thread2 = threads->new(\&!loop. ^second'): 
my ^thread! = threads->iiew(\&loop. ‘third’ ): 

It is imporrant to remember that yieldQ is only a hint to give 
up die CPU, it de|>ends on your fiardware, 08 and threading 
libraries what actually happens. On many operating systems, 
yieldO ks a no-op, 'Pherefore ti is important to note that one 
should not build the scheduling of llie tlireads around yield() 
calls. It might work on your platform l>ut il wont work on 
another platform, 

8. Geiverai, Thread Um jit Routines 

WeVe covered the workhorse parts of PerPs thi*eading 
package, and witli tlicsc UkjIs you should be well on your way 
to writing thre^ided code and packages. There are a few useful 
little pieces that didn't really fit in anyplace else. 
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what Thread Am IM? 

The threadS">self class method provides your program wiih 
a way to get an object representing the thread it's currently in. 
You can use this ol)jcct in the same way as the ones returned 
from tliread creation. 

Thread IDs 

tidO is a thread object method thxit returns the thread ID of 
the thread the objea represents. Thread IDs are inlugcrs, witli 
the main thread in a program lacing 0. Currently Perl assigns a 
unique tid to every thread ever aeated in your prt)gram, 
assigning the first thread to be created a tid of 1, and increttsing 
the tid by 1 for each new thread lhafs created. 

Are These Tlireads llie Same? 

T!ie ec|ual0 metliod takes two tliread objecLs and returns tnie 
if tlie objecTs represent the same thread, and false if the>" don't. 
Thread objects also have an overloaded comparison so 
that you can do comparison on them as you would with nomial 
objects. 

What Threads Are Running? 

dircads->list returns a list of thread objects, one for each 
thread thafs currently running and not detached. Handy for a 
numlier of things, including cleaning u[> at the end of your 
prt>gram: 

# Loop through all the threads 
foreach ^thr (threads‘>list) I 

If Don't join the min thread or ourselves 
if ($thr->tid !threads::equal{$thr, threads‘>self)) f 

$dir->join; 

I 

I 

If some threads have noi finished running when the 
main Perl ttjrcad ends, Perl will warn you about it and die, 
since it is impossible for Perl to clean up itself while other 
threads are running 

% A Complete Example 

Confusetl yet? It's rime for an example program to .show 
some of the things weVe covered. Tliis jirograni finds prime 
numbers u,sing threads. 

1 If l/usr/binyperl w 

2 # prime-pthread, courtesy of Tom Christiansen 

3 

h use strict; 

5 

6 use thread,';; 

7 use Thread::Queue: 

8 

9 Biy $streatii ^ new Thread;:Queue: 

10 my $kid= new threadst\&check_nuM, $streaiii. 2) ; 

U 

12 for my $i ( 3 .. 1000 ) [ 

13 $stre3m->enqueue($ij; 

H J 

15 

16 ^stream->enqueueCundef): 

17 $kid->join: 

18 


19 sub check_num t 

20 my t$upstreaiB* $cur_pri[tie) " 

21 my $kid: 

22 my $downstream = new Thread::Queue; 

23 while (my $nuiii = $upatream-)dequeue) ( 

7A next unlesfl $num % $cur_prime: 

25 if f$kld) ( 

26 $downBtream->enqueueC$num): 

2/ I else ] 

28 prinL '"Found prime $mLm\n'': 

29 Skid = new threads (Heheck_Tium, Sdownst ream, 
$uum): 

30 I 

31 J 

32 Sdownstream->enqueue(undef) if $kid: 

33 Skid->join if Skid; 

34 1 


This program uses the pipeline model to generate prime 
numbers. Each thread in the pipeline has an input queue that 
feeds numbers to be checked, a prime number that iPs 
responsible for, and an output t)ucue into which it funnels 
numbers dial have failed the check. If the thread has a 
number that's failed its check and there’s no child thread, 
then the thread must have found a new prime number. In 
that case, a new child thread is created for that prime and 
stuck on the end of the pipeline. 

'Ihis probably sounds a bit more confu.sing than it really is, 
so let's go through lliis program piece by piece and see what it 
does. (For tho.se of you who might lie trying to rememl:)er 
exactly what a prime number is, it's a numlxrr that's only evenly 
divisible by itself and 1) 

The hulk of the work is done by the check_num(} 
subroutine, which rakes a reference to its input queue and a 
prime numlier that it s responsible for. Alter pulling in the input 
queue and the prime that the subroutine's checking (Une 20), we 
create a new queue (line 22) and reserve a scalar for the thread 
that w'e're likely to create later (line 21). 

Tile while loop from lines 23 to line 31 grabs a scalar off 
the input queue and checks against the prime this thread is 
responsible for. Line 24 checks to see if ihere's a remainder 
w hen we modulo the numlrer to l^e checked against our prime. 
If there ts one, the number must not be evenly divisible by ont 
prime, so we need to either pass it on to the next thread if weVe 
created one (line 26) or create a new thread if we haven't. 

Tlie new thread creation is line 29- We pass on to it a 
reference to the queue weVe created, and die prime number 
we've found. 

Finally, once the kx>p terminates (l^ecause we got a 0 or 
iindef in the queue, which serves as a note to die), wc pass on 
the notice to our child and wail for it to exit if we’ve created a 
child (lines 32 and 37). 

Meanwhile, back in the main thread, we create a queue 
(line 9) and die inhial child thread (line 10), and pre-seed it with 
die first prime: 2. Then we queue all the numbers from 3 to 1000 
for checking (jines 12-14), then queue a die notice (line 16) and 
wait for the first child thread to terminate (line 17). Because a 
diild won’t die until its child has died, we know that we're done 
once we return from the join. 
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Thac's hcjw ii works. It's pretry' simple; as wiih niany Perl 
pr()|?ramH, the explanatit^n ts miieh longer than the program. 

10. Different impt^ementations of TiiiuiADS 

Some l)ackgrouiul on thread implementaiions froni die 
t)ix?raling system viewpoint. There are tiiree basic categories of 
threads: nser-nKxie ilirL-ads, kernel threads, and muliiprtK'essor 
kernel threads. 

User-mode threads are threads that live entirely within a 
program and its lihraries. tn this model, the OS knows 
nothing about threads. As far as it“s concerned, your process 
is just a process. 

This is the easiest way lt> implement threads, and the way 
most OSes start, Tlie big disadvantage is ihai, since die OS 
knt>ws nothing a!x>ut ihreacLs, if one tiiread bltK’ks they all do. 
Typictil bloc'king aclivities include most system c'alls, inosi I/O, 
and things tike sleepO, 

Kernel thread.? are the next step in thread evolution. The 
knows alxmt kernel threads, and makes allowances for them, 
'I1ie main difference liciwecn a kernel thread and a user-mode 
thread ts bkx:king. With kernel threads, things that Idock a .single 
thread don’t block other thrcratls. This is not the case with u.ser- 
mode threads, where llie kernel blocks at the process level and 
not the dirtrad level, 

'Iliis is a big step forward, and can give a threaded program 
quite a performance Ixjost ovct rioii-threaded programs, Ttireads 
that block fx:rforming I/O, for example, w'oiVt bltK'k threads that 
are doing otlier things, tkich process still has only one thread 
running at once, though, regardless of how many CPUs a system 
might have. 

Since kernel threading can internipi a thread at any time, 
they will uncover ,some of the implicit lockiiig assitmptions you 
may make in yoiir program. For examplL% something as .simple 
as $a = $a + 2 can behave unpredictably with keniel threads if 
Sa is visible to other thread.?, as anotlier thread may have 
changed $a between the time it was fetched on the right hand 
side and tlie lime llie new value is storetl. 

Multiprocessor kernel threads are tiie final step in thread 
support. With multiprocessor kernel thread.? on a machine w'ilh 
mu! Li pie CPUs, die OS may schedule two or more threads to nin 
simultaneou.sly on differcni CPUs. 

'Ibis am give a serious [jeriormance Ixxasi to your threadetl 
program, since tiiore than t>ne thread wall be executing at the 
same time. As a inideoff^ though, any of those nagging 
synchroniziition issues lltat might not have showm with basic 
kernel threads wall ap(X"Ur with a vengeance. 

In addition to the different levels (j 1 OS involvement m 
threads, differeni OSes (and different thread implementations for 
a particular OS) allocate CPU cycles to threads in different ways. 

Qjoperative multitasking systems have running threads give 
up control if one of two i hings liapfK'n, [f a thread calls a yield 
fttndion, it gives up control. It also gives up control if the thread 
docs something that would cause it to bk>ek, such as perfonn 
I/O, In a ccK)perative multitasking implementation, one thre^id 
can starve all tlie others for CPU time if it so chooses. 


Preemptive muliiuisking .systems interrupt threads at regular 
intervals while the systein deckles which thread slum Id run next. 
In a preemptive multitasking system, one thread usually won't 
monopolize the CPU. 

On .some systems, there can be cooperative and preetnptive 
threads running simultaneously. (Threads running with realtime 
priorities often behave ccM>txTalively, for example, wiiile threads 
ainning at normal priorities l>e!iave preemptively.) 

Most mcjdern operating systems su[i|iort preemptive 
multitasking now'adays, 

n . Performance considerations 

The main thing to bear in mind when comparing ithreacLs to 
other threitding models is the fact dial for each new thread 
created, a complete copy of all the variables and data of the 
[>arcnt thread has to Ix" taken. Thus thread creation can quite 
ex[xmsive, toih in terms of memoiy usage and time sptmt in 
creation. Tlie ideal way to reduce these ctxsls is to have a 
relatively short nuruber of long-lived thread,?, all created fairly 
early on - before the base tliread has accumulated too much 
dam. Of course, this may not always lx* possible, so 
annprtjmLses have to lx made. Howxwer, alier a thread has Ixen 
created, its performance and extra menioiy usitge should be liulc 
different than ordinary code. 

Also note that under the current implementatiun, shared 
variables use a little more memorv^ and are a little slower than 
ordinaiy variables. 

12- Process-scope Ciiangf^ 

Note that while dircads themselves are separate execution 
threads and IfoTl data is thread-privale unless explicitly shared, 
the thraids can affect prfK'es.s-scope slate. alTeding all the 
threads. 

rhe most common example of this is changing the current 
working directory using chditl). One thread calls chdirO, and 
the working direaory of all ihe ihrc‘ads changes. 

bven more drastic example of a pitHess-scope change is 
clmxHO: the root dirermry of all the ihre^ids changes, and no 
thread on undo it (a.? opfxxscd to chdiri)). 

Further examples of process-scope changes include 
iiniaskt) and changing tiids/gids. 

Thinking of mixing forkf) and threads? Please lie down and 
w'ait Linlil the feeling j^usse.s— but in case you really want to 
know, the semantics Is that forkO duplicates all the threads. (In 
UNIX, at least, other plailbnns will do stjmething different.) 

Similarly, mixing signals and threads shtiuid not Ixr 
attemfMcd. Implemetitalions are piatform-defK^ndent, and even 
the POSIX semantics may not Ix^ what you expect (and Perl 
tk>esnT ev^en give you the full POSIX Aid), 

13. Thread-Saj eit of System Ubraries 

whether various library calls are rhread-s;ife is outside the 
control of Perl. Calls often sulTering from nt)i Ixang thread-safe 
incl ude: iocaitiiiief), gmtitTie<), getIgr,I u >st,net,|>rolo,s€rv,pwP(), 
readdirf), randO, and srandf)^— in general, calls that depend on 
some global external stale. 
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If the system Perl is com pi feci in has thread-sale* variants of 
such calls, they will be used. Beyond that, Perl is at the mercy 
of [lie tliread-safety or -uasafety of the calls, Plcrase consult your 
C library caM docutnentation. 

On some platfoniis ilie iliread-safe library interfaces may 
fail if the result buffer is too stnall (for example the user group 
databases may be rather large, and the reentrant interfaces may 
have TO carry around a full snapshot of those databases). Pt?rl 
will Stan with a small buffer, but keep relryir^g and growing die 
result buffer until the result fits. If this liniiiles,s growing sounds 
bad for security or memory ('onsumption reasons you can 
recompile Perl with FHRL_Rlii:NTRANT„MAXSlZb: defined to tlie 
maximum nunilx^T of bytes you will allow. 

14. Conclusion 

A com[>leie ihreaci tutorial could fill a book (and has, ni;my 
limes), but with what we’ve covered in this introduction, you 
should lie well on your way to lx;coming u threaded Perl ex|X"rt. 
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Multiple fonnats. Multiple platfonns. 
Complex installers. 

Aladdin solves the compressbn and installation puzzle. 


Trying to figure out how to handle multiple 
compression fonnats and platfonns? 

The Stuffit Engine solms the compression puzzle. 

Aladdin's Stuffit Engine SDK: 

> Adds value to your application by integrating powcrfiil compression and encryption. 

> Is the only tool tliat supports the Stuffit file fonnat. 

► Providis a single API that supports over 20 compression and 
encoding formats common on Macintosh, Windows, and Unix. 

► Makes .self-extracting archives for either Macintosh or Windows. 

>• Available for Macintosh, Windows, Linux, or Solaris. 


liceitiies stan as Low 
as 

To leam more, visit: 
www.stuffilcoiTi/sdk/ 



stuffit Engine SDK~ 

The power of Stuffit in your software. 



Looking for the easiest and fostest 
way to build an installer? 

Stuffit InstallerMaker completes your puzzle. 


It’s not enough just to write solid code anymore. You still have to write an installer 

for your users. Stuffit InstallerMaker makes it simple and effective. 

>■ Stuffit InstallerMaker gives you all the tools you need to install, uninstall, 
resource-compress or update your software in one complete, 
easy-to-use package. 

► Add marketing muscle to your installers by customizing 
your electronic registration form to include surveys 
and speci:d offers. 

► Make demoware in minutes. Create Macintosh 
OS X and Macintosh Classic compatible installers 
with Stuffit InstallerMaker. 

Stuffit InstallerMaker 

The complete installation solution."” 


IMces Stan m $250 

To leam more, visit: 
www,stuffitxom/ 
insiallermaker/ 


- ^ Aladdin 
wXSystetfis’i 

www.stuffit.com 
(831) 761-6200 

0 2002 Aladdin Sysieffls. 
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Introducins 

Dreamcard: build it 
Software design & programming 
for the rest of us... 

Make multimedia, games and applications 
Learn and teach how a computer really works 
Make professional-looking software - easily! 


Revolution 


Revolution 

Dreamcari 


Just released - 2.5 

Revolution: develop it 
Application design & programming 
for professionals... 

Prototype & design using rapid-build tools 
Develop directly in a runtime environment 
Create multi-platform 
standalone applications • easily! 
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Revolution: develop it 


Dreamcard; build it Suiiw^re d«.jn 
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User-Centric Development i 

Runtime Revolution • 15-19 York Place • Edinburgh EHl 3EB • Scotland * UK 
Phone +44 [0) 870 747 1165 • Fax +44 (0) 845 458 8487 • www.runrev.com • Email info@runrev.com 


www.runrev.com 

Some things ••• 

Are too good 

to leave 

behind.^ 
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